Stabilize Prometheus Native Histogram -> OTLP (Exponential) Histogram

[krajorama]

Fixes #4748

Changes

Enacted from #4748 (comment)

• The counter reset header is not mentioned -added
• Stale NaN is not defined in the document - added link to code where the bit representation can be found
• Conversion of spans and counts is a bit hand-wavy, I understand why you'd want to link to something - added precise wording and link
• Off by one of the offset is mentioned, but it doesn't say if it's -1 or +1 - precise now with explanation
• NHCB (-53) schema is missing indeed - added
• Prometheus has renamed the Created timestamp to Start timestamp to be more aligned
• I'm not sure if the overflow buckets of native histograms are handled or how they work in OTel. Where do you count - values equal to +-Inf or values outside float64 ? - these were indeed not handled, specified now

Additionally added notes on Count and Sum for special value cases. Note that the OTel metric data model does not have "MUST" requirements on the special values or if the overall Count must be equal to the sum of all buckets.

For non-trivial changes, follow the change proposal process.

• Related issues #
• Related OTEP(s) #
• Links to the prototypes (when adding or changing features)
• CHANGELOG.md file updated for non-trivial changes
  • For trivial changes, include [chore] in the PR title to skip the changelog check
• Spec compliance matrix updated if necessary

[dashpole]

I'm still nervous about "leaking" the NHCB concept outside of the prometheus server / prometheus receiver. E.g. SDK bridges from Prom -> OTel would never need to implement this... WDYT about leaving this out of the specification and considering it implicit in the (classic) histogram section.

[krajorama]

Well the prometheusreceiver will receive NHCB from scrape and the prometheusremotewritereceiver can receive them over Remote-Write 2.0 , so I'm not sure we can ignore it. I think this is the correct place for it. At least I would search for it here.

[dashpole]

I'm not that concerned about the prometheus receiver, as we rely on lots if internal implementation details of the prometheus server. But if we do it in PRW 2.0, then the cat is out of the bag (it is part of protocols now).

I still think this would make more sense to document this as part of the histogram section, as translation will largely follow the rules in that section. Maybe something like "In some cases, classic prometheus histograms are represented as Native Histograms with the schema -53 for performance or cost reasons. These are referred to as "Custom Bucket native histograms". Such histograms MUST follow the same rules for classic histograms below."

[krajorama]

I've moved the text to Histograms: 46d0f72

I think it looks terrible. And not consistent with how Prometheus documents NHCB. For Prometheus NHCB is a native histogram. Also not sure how to handle the last sentence in the native histograms: "Native Histograms with Schema outside of the range [-4, 8] and not equal to -53 MUST be dropped."

[krajorama]

Also the histogram part is stable, so I don't know if we can make this change?

[dashpole]

Also the histogram part is stable, so I don't know if we can make this change?

Usually we would add a development header above the new text if we wanted to do that.

But reading it I agree with you. I had imagined that we could say "here is how you get a Prometheus histogram from NHCB", and then just point to the histogram spec. But if we write it as a complete section it does look out of place. Sorry for the churn, you can revert to what you had previously.

[krajorama]

thank you, reverted