diff --git a/observability/WFLY-18582_add-prometheus-endpoint-to-micrometer-extension.adoc b/observability/WFLY-18582_add-prometheus-endpoint-to-micrometer-extension.adoc new file mode 100644 index 00000000..48fd1452 --- /dev/null +++ b/observability/WFLY-18582_add-prometheus-endpoint-to-micrometer-extension.adoc @@ -0,0 +1,117 @@ +--- +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: jasondlee@redhat.com +: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) +* 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. + +=== 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.