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.

[sed-i]

Thanks @danielgblanco, @svrnm.
I'm also curious if this proposal overlaps with semantic conventions.
Iiuc, app devs would use weaver for that?

I'm new to otel so apologies about the ignorance 😅

[svrnm]

Hey @sed-i,

the proposal does not overlap with semconv/weaver but will eventually be a consumer of that data. If you review the proposal and provide your feedback there that would be appreciated, since it helps to capture everything at one place. Note that this proposal is in draft state on purpose, since I do not have the bandwidth to execute it right now, so we are also looking for people to address this.

Thanks

[danielgblanco]

Hi @sed-i, would it be okay to close this issue and focus efforts on the project proposal above?