improve the metrics integration documentation

doc/modules/ROOT/pages/integration/metrics.adoc

@@ -3,40 +3,66 @@
 {smallrye-fault-tolerance} provides support for MicroProfile Metrics and Micrometer.
 Alternatively, metrics may be completely disabled at the integration level.
 
-As usual, this integration is based on CDI, so an integrator must select one of the following classes and add it to the set of types scanned during CDI bean discovery:
+As usual, this integration is based on CDI.
+{smallrye-fault-tolerance} includes an internal interface `MetricsProvider` and 3 different implementations.
+Exactly 1 bean of type `MetricsProvider` must exist.
+An instance of that bean is used to interact with the metrics system.
+
+There are 2 ways to select which metrics provider bean exists:
+
+- using a constructor of the Portable Extension,
+- altering the set of discovered types.
+
+== Using a `FaultToleranceExtension` Constructor
+
+In case the integrator uses the CDI Portable Extension `FaultToleranceExtension` and creates its instance manually, they can use a constructor.
+
+In addition to a zero-parameter constructor, there's a constructor that takes a `MetricsIntegration` parameter.
+`MetricsIntegration` is an enum with these values:
+
+* `MICROPROFILE_METRICS`: use MicroProfile Metrics integration
+* `MICROMETER`: use Micrometer integration
+* `NOOP`: no metrics
+
+As mentioned above, this is only useful if the integrator creates an instance of the extension themselves.
+If the integrator relies on the CDI container to discover and instantiate the extension, the zero-parameter constructor is used, which defaults to `MICROPROFILE_METRICS`.
+Such integrator can use the 2nd approach of altering the set of discovered types.
+
+== Altering the Set of Discovered Types
+
+The integrator may select the metrics provider by making sure that the correct implementation is discovered during CDI type discovery.
+The existing metrics providers are:
 
 * `io.smallrye.faulttolerance.metrics.MicroProfileMetricsProvider`
 * `io.smallrye.faulttolerance.metrics.MicrometerProvider`
 * `io.smallrye.faulttolerance.metrics.NoopProvider`
 
-All these classes implement an internal interface `MetricsProvider`.
-This interface, together with an internal core interface `MetricsRecorder`, is used by the rest of {smallrye-fault-tolerance} to interact with the metrics system.
-
 NOTE: Only the _names_ of the classes listed above are treated as public.
 That is, the classes should be treated as opaque, no guarantees about their internals are made.
 
-The possibility to choose a metrics implementation is currently mainly provided for Quarkus.
-The CDI Portable Extension present in {smallrye-fault-tolerance} always assumes MicroProfile Metrics are required.
+Exactly one of these classes must be discovered during CDI type discovery.
+
+NOTE: Integrators that rely on the CDI container to instantiate `FaultToleranceExtension` must be aware that in this case, the extension adds `MicroProfileMetricsProvider` to the set of discovered types.
+If they want to use a different metrics provider, they need to veto the `MicroProfileMetricsProvider` type.
+
+== Metrics Providers
 
 Metrics providers have additional requirements, as described below.
 
-== MicroProfile Metrics
+=== MicroProfile Metrics
 
 If MicroProfile Metrics are used, the integrator must ensure that the following artifacts are present:
 
 * `org.eclipse.microprofile.metrics:microprofile-metrics-api`;
 * some implementation of MicroProfile Metrics.
 
-NOTE: As mentioned above, when an integrator relies on the CDI Portable Extension provided by {smallrye-fault-tolerance}, this is currently the default and only option.
-Therefore, presence of MicroProfile Metrics is mandatory for those integrators.
-
-== Micrometer
+=== Micrometer
 
 If Micrometer is used, the integrator must ensure that the following artifact is present:
 
 * `io.micrometer:micrometer-core`.
 
-== Noop
+=== Noop
 
 If the "noop" provider is used, metrics are completely disabled and the `MP_Fault_Tolerance_Metrics_Enabled` configuration property is ignored at runtime.
 

doc/modules/ROOT/pages/integration/programmatic-api.adoc

@@ -12,7 +12,7 @@ A single cached thread pool, obtained using `Executors.newCachedThreadPool()`, i
 
 Users of the standalone implementation that also use an event loop based library, such as Vert.x, may integrate the event loop support as described in xref:integration/event-loop.adoc[Event Loop].
 
-== CDI implementation
+== CDI Implementation
 
 The CDI implementation will use the thread pool an integrator provides (see xref:integration/thread-pool.adoc[Thread Pool]).
 This also extends to the context propagation integration (see xref:integration/context-propagation.adoc[Context Propagation]).