Prevent duplicate Prometheus description comments

[dashpole]

Fixes #2869

Follow-up to #2703. That PR prevents collisions between data points, but not collisions between the descriptions of the metrics.

OpenMetrics requirements

From https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metricfamily:

A MetricFamily MUST have a name, HELP, TYPE, and UNIT metadata.
MetricFamily names are a string and MUST be unique within a MetricSet.

Basically, for a given metric name, we MUST have exactly one HELP, TYPE, and UNIT comment.

Changes

This is a bit light on details, but I can add more if people think that would be helpful.

Basically, this is saying that exporters need to deduplicate Prometheus "descriptions" when sending. For TYPE conflicts, some metric has to be dropped, as the data sent might not be valid (e.g. you can't send counter information with a histogram TYPE). For UNIT and HELP comments, it is up to the exporter how to merge, but the exporter MUST NOT keep both comments.

Example approach

• Keep a map of metric name -> Description when constructing a batch of metrics for a scrape.
• Each time a new metric (with Description) is added, look up the name in the map:
  • If it isn't found, add it to the map
  • If it is found, and the desc is the same, do nothing
  • If it is found, and has conflicting type information, drop the metric + log a warning
  • If it is found, and has conflicting help or unit, use the stored help + unit instead of the provided one + log a warning.

[dashpole]

cc @jack-berg @reyang @open-telemetry/wg-prometheus

[reyang]

LGTM although I'm a bit on the fence https://github.com/open-telemetry/opentelemetry-specification/pull/2890/files#r998590686.

[reyang]

@dashpole would you update the changelog?

[dashpole]

@dashpole would you update the changelog?

Done