Manifest for metrics endpoint

[sed-i]

Problem

Currently, there is no obvious way to obtain the metrics an application exposes, without first deploying the application.

Proposal

Come up with a standard for documenting the metrics an application exposes. This could take different forms, for example:

• A METRICS.md file with a sample contents of /metrics.
• Store organically to the app, in the same repo (and optionally link there from the dockerhub image page).
• A build artifact of a release, adjacent to the binary/packages published as part of the release.

Value proposition

1. Deprecation of metrics, or introduction of new metrics would be readily noticed.
2. Metric names used in alert expressions or dashboard panels could be more easily linted against the manifest(s), flagging those that rely on no longer existing metric names (modulo recording rules).
3. Users would be able to make informed decisions about alternative applications, based on how they are instrumented, and without needed to first deploy them.

Additional context

• If some of the metrics are conditional (e.g. per-path latency metric), it would be tricky to generate them (would need to query the particular path), but it’s not a big deal if they are missing from the advertized manifest, because: (a) afaik conditional metrics are considered bad practice; (b) usually, it’s only the labels that carry the per-path info.

Prior art

• https://github.com/utkuozdemir/nvidia_gpu_exporter/blob/master/METRICS.md

[danielgblanco]

Hi @sed-i, normally this time of proposal would come as a new project project in our community repo, or as an OTEP. Having said this, @svrnm has a draft for a project proposal on this same topic. I think it could meet the requirements above and integrate with our Registry.