diff --git a/docs/src/main/asciidoc/se/fault-tolerance.adoc b/docs/src/main/asciidoc/se/fault-tolerance.adoc index 5ad7e3eca2b..df92a6ab493 100644 --- a/docs/src/main/asciidoc/se/fault-tolerance.adoc +++ b/docs/src/main/asciidoc/se/fault-tolerance.adoc @@ -1,6 +1,6 @@ /////////////////////////////////////////////////////////////////////////////// - Copyright (c) 2020, 2024 Oracle and/or its affiliates. + Copyright (c) 2020, 2025 Oracle and/or its affiliates. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -259,6 +259,81 @@ and bulkhead is the last one (the first to be executed once a value is returned) NOTE: This is the ordering used by the MicroProfile Fault Tolerance implementation in Helidon when a method is decorated with multiple annotations. +== Metrics + +The Helidon Fault Tolerance module has support for some basic metrics to monitor +certain conditions. Metrics are disabled by default, but can be enabled via config by +setting the property `ft.metrics.enabled=true` and by including an actual metrics +implementation in your classpath. + +``` + + io.helidon.metrics + helidon-metrics + +``` + +The following tables lists all the metrics created by the Fault Tolerance module. +Note that these metrics are generated per instance, and that each instance _must_ +be identified by a unique name --assigned either programmatically by +the application developer or automatically by the API. + +[cols="1,2,3"] +.Bulkheads +|=== +^|Name ^|Tags ^|Description +|ft.bulkhead.calls.total | name="" | Counter for all calls entering a bulkhead +|ft.bulkhead.waitingDuration | name="" | Histogram of waiting times to enter a bulkhead +|ft.bulkhead.executionsRunning | name="" | Gauge whose value is the number of executions running in a bulkhead +|ft.bulkhead.executionsWaiting | name="" | Gauge whose value is the number of executions waiting in a bulkhead +|=== + +[cols="1,2,3"] +.Circuit Breakers +|=== +^|Name ^|Tags ^|Description +|ft.circuitbreaker.calls.total | name="" | Counter for all calls entering a circuit breaker +|ft.circuitbreaker.opened.total | name="" | Counter for the number of times a circuit breaker has moved from +closed to open state +|=== + +[cols="1,2,3"] +.Retries +|=== +^|Name ^|Tags ^|Description +|ft.retry.calls.total | name="" | Counter for all calls entering a retry +|ft.retry.retries.total | name="" | Counter for all retried calls, excluding the initial call +|=== + +[cols="1,2,3"] +.Timeouts +|=== +^|Name ^|Tags ^|Description +|ft.timeout.calls.total | name="" | Counter for all calls entering a timeout +|ft.timeout.executionDuration | name="" | Histogram of all execution durations in a timeout +|=== + +=== Enabling Metrics Programmatically + +Metrics can be enabled programmatically either globally or, if disabled globally, individually for +each command instance. To enable metrics globally, call `FaultTolerance.config(Config)` passing +a Config instance that sets `ft.metrics.enabled=true`. This must be done on application startup, +before any command instances are created. + +If metrics are not enabled globally, they can be enabled programmatically on each command instance +using the `enableMetrics(boolean)` method on its corresponding builder. For example, the +following snippet shows how to create a `Retry` instance of name `my-retry` with metrics +support enabled. + +[source,java] +---- +include::{sourcedir}/se/FaultToleranceSnippets.java[tag=snippet_8, indent=0] +---- + +NOTE: The global config setting always takes precedence: that is, if metrics are enabled +globally, they *cannot* be disabled individually by calling `enableMetrics(false)`. + + == Examples See <> section for examples. diff --git a/docs/src/main/java/io/helidon/docs/se/FaultToleranceSnippets.java b/docs/src/main/java/io/helidon/docs/se/FaultToleranceSnippets.java index c13fcd6a6d5..90d8e7416e1 100644 --- a/docs/src/main/java/io/helidon/docs/se/FaultToleranceSnippets.java +++ b/docs/src/main/java/io/helidon/docs/se/FaultToleranceSnippets.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2024 Oracle and/or its affiliates. + * Copyright (c) 2024, 2025 Oracle and/or its affiliates. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -127,4 +127,13 @@ void snippet_7() { T result = builder.build().invoke(this::mayTakeVeryLong); // end::snippet_7[] } + + void snippet_8() { + // tag::snippet_8[] + Retry retry = Retry.builder() + .name("my-retry") + .enableMetrics(true) + .build(); + // end::snippet_8[] + } }