[WFLY-18582] Add prometheus endpoint to micrometer extension

Add analysis document

observability/WFLY-18582_add-prometheus-endpoint-to-micrometer-extension.adoc

@@ -0,0 +1,123 @@
+---
+categories:
+ - observability
+---
+= WFLY-18582 - Add prometheus endpoint to micrometer extension
+:author:            Jason Lee
+:email:             [email protected]
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+== Overview
+
+Micrometer replaced Micrometer Metrics as the user-facing metrics library provided by WildFly. As part of that
+transition, the export behavior moved from a pull-based Prometheus-like format to push-based mechanism using the
+OpenTelemetry Protocol. Based on feedback from users who still desire to use the pull-based approach, this change will
+add support for the Prometheus Registry in addition to or in place of the OTLP Registry.
+
+== Issue Metadata
+
+=== Issue
+
+* https://issues.redhat.com/browse/WFLY-18582[WFLY-18582]
+
+=== Stability Level
+// Choose the planned stability level for the proposed functionality
+* [ ] Experimental
+
+* [X] Preview
+
+* [ ] Community
+
+* [ ] default
+
+
+=== Dev Contacts
+
+* mailto:{email}[{author}]
+* mailto:[email protected][James Perkins]
+
+=== QE Contacts
+
+=== Testing By
+* [x] Engineering
+
+* [ ] QE
+
+=== Affected Projects or Components
+
+Only the Micrometer subsystem and related tests will be affected
+
+=== Other Interested Projects
+
+- OpenShift has an interest in Prometheus metrics
+
+=== Relevant Installation Types
+* [x] Traditional standalone server (unzipped or provisioned by Galleon)
+
+* [ ] Managed domain
+
+* [x] OpenShift s2i
+
+* [x] Bootable jar
+
+== Requirements
+
+=== Hard Requirements
+
+* Existing servers, if configured to use Micrometer (e.g., the `endpoint` property has been set), will be migrated to be
+an OTLP-based configuration. Since OTLP is the only current option, there is no ambiguity in this migration.
+* Existing servers with the extension enabled but with no endpoint set will not be changed. That is to say, Micrometer
+will continue to use a no-op registry.
+* Support for a new registry, `PrometheusRegistry` will be added.
+** It can be added as the only registry, or it can be added _in addition to_ the OTLP Registry
+** The registry will expose two model attribute:
+*** context: the context (e.g., `/prometheus`) on which the metrics will be exposed
+*** security-enabled: whether or not to secure the context using the user and roles defined in the application server
+** If the user would like to use `/metrics`, the WildFly metrics extension must be disabled first to avoid a naming conflict.
+
+=== Non-Requirements
+
+* Adding other arbitrary `MeterRegistry` types
+
+== Backwards Compatibility
+
+* Existing servers should continue to operate as is, using any existing OTLP configuration without manual intervention.
+
+=== Default Configuration
+
+* The default context for the Prometheus scrape will be undefined and must be specified by the user when enabling support (`context`)
+* The context will be secured (`security-enabled`) by default
+
+=== Importing Existing Configuration
+
+* See above.
+
+=== Deployments
+
+=== Interoperability
+
+== Security Considerations
+
+If `security-enabled` is set to true:
+
+* The endpoint will use basic authorization to control access to the endpoint itself
+* As each metric is read, the system will verify that the authenticated user has access to that particular metric before returning the value.
+** All metrics that are disallowed for the user per the security policy will return a zero
+
+== Test Plan
+
+* Tests will be added to `testsuite/integration/microprofile/`
+** Verify basic Prometheus support
+** Verify security can be enabled
+
+== Community Documentation
+
+The WildFly Administration Guide will be updated to include this new support.
+
+== Release Note Content
+
+The Micrometer extension has been modified to add support for the Prometheus Registry, allowing for pull-based/scraping
+of metrics information for deployments where that is preferred.