Story: I am an administrative or developer user of the OpenShift Monitoring stack trying to configure metrics, and I want to know what metrics are available as well as what each metric measures and how it should be used. I should be able to go to the OpenShift documentation and find complete reference information readily available.

Existing documentation: As of OCP 4.9, the current OpenShift Monitoring documentation doesn't document the Prometheus metrics included in a default installation of the OpenShift Monitoring stack. This info also doesn't seem to be available in the upstream Prometheus documentation either.

Business case: Customers would benefit from a documented list of metrics that are included (see the RFE in BZ 170893). Also, the Monitoring engineering team reports that this information is asked for regularly by Monitoring users.

Definition: Ideally, metrics reference information will be autogenerated in AsciiDoc format by a utility that creates files that can be added to the openshift-docs repository for use in customer-facing documentation.This autogenerated file will then be added to the OCP doc set for every release by the docs team.

The generated file's format and organization is TBD, but should include the metric's type as well as a short description. If relevant, it should also include the support level for each metric (e.g. GA vs. Tech Preview).

Also desirable would be for the AsciiDoc file to be automatically regenerated and updated whenever a metric is added/updated/dropped in the code and for the CI to automatically verify that the committed documentation matches with the code.

(This issue was originally raised by the OpenShift Networking team in https://issues.redhat.com/browse/OSDOCS-2679.)