[WFLY-18582] Add prometheus endpoint to micrometer extension

Add analysis document
Update to new AD format

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

@@ -0,0 +1,119 @@
+---
+categories:
+- observability
+stability-level: community
+issue: https://github.com/wildfly/wildfly-proposals/issues/590
+feature-team:
+ developer: jasondlee
+ sme:
+  - jamezp
+ outside-perspective:
+  - kabir
+---
+= [Community] 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]
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/EAP7-2234[EAP7-2234]
+* https://issues.redhat.com/browse/EAP7-2235[EAP7-2235]
+
+
+=== 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
+
+* Traditional standalone server (unzipped or provisioned by Galleon)
+* OpenShift Source-to-Image (S2I)
+* Managed domain
+* Bootable jar
+
+== 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 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.
+* Micrometer, using its OTLP-based push approach, should continue to work in manage domain mode, but if Prometheus is configured to be used on the host controller, the startup attempt of the HC should fail.
+
+=== 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
+
+Deployments will be unaffected by this change, as it is of interest only to system administrators or metrics dashboard maintainers.
+
+=== Interoperability
+
+== Security Considerations
+
+* Users must be in the management realm
+* 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]]
+== Test Plan
+
+* Tests will be added to `testsuite/integration/microprofile/`
+** Verify basic Prometheus support
+*** A user application will be deployed to a running server (via Arquillian)
+*** Prometheus metrics will be scraped to verify that application metrics are being exported
+*** JVM/System metrics will also be verified by a scrape
+** Verify security can be enabled
+*** Access to the endpoint will be verified with security disabled
+*** Security will be enabled, and access checks will be verified:
+**** Unauthenticated requests will be verified to be rejected
+**** Properly authenticated requests will be verified to be allowed
+
+== 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.