Skip to content

[Prometheus and OpenMetrics] Handle scheme URL and scope attributes as identifying #4223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
pellared opened this issue Sep 24, 2024 · 22 comments · Fixed by #4505
Closed

[Prometheus and OpenMetrics] Handle scheme URL and scope attributes as identifying #4223

pellared opened this issue Sep 24, 2024 · 22 comments · Fixed by #4505
Assignees
Labels
sig-issue A specific SIG should look into this before discussing at the spec spec:metrics Related to the specification/metrics directory triage:accepted:ready Ready to be implemented. Small enough or uncontroversial enough to be implemented without sponsor

Comments

@pellared
Copy link
Member

pellared commented Sep 24, 2024

I think this needs updates to some of the compatibility docs (at least prometheus). Currently, Prometheus adds scope name and scope version as labels to ensure we don't end up with duplicate timeseries, and we are able to put scope attributes in a separate otel_scope_info metric. With this change, we will need to update this to instead add the scope name, scope version, and scope attributes to all metrics.

TIL schema_url is also identifying, so that is something we will need to handle in Prometheus export and other "non-OTLP" compatibility documents.

Originally posted by @dashpole in #4161 (comment)

@pellared pellared added the spec:metrics Related to the specification/metrics directory label Sep 24, 2024
@pellared
Copy link
Member Author

@dashpole, are you able to take this?

@dashpole
Copy link
Contributor

cc @open-telemetry/wg-prometheus

Yes, I'll take this

@dashpole dashpole self-assigned this Sep 24, 2024
@svrnm svrnm added sig-issue A specific SIG should look into this before discussing at the spec triage:accepted:ready Ready to be implemented. Small enough or uncontroversial enough to be implemented without sponsor labels Sep 30, 2024
@pellared pellared changed the title [Prometheus] Make instrumentation scope as identifying [Prometheus] Add otel_scheme_url label to otel_scope_info metric Oct 28, 2024
@pellared pellared changed the title [Prometheus] Add otel_scheme_url label to otel_scope_info metric [Prometheus and OpenMetrics] Add otel_scheme_url label to otel_scope_info metric Oct 31, 2024
@pellared pellared changed the title [Prometheus and OpenMetrics] Add otel_scheme_url label to otel_scope_info metric [Prometheus and OpenMetrics] Handle scheme URL and scope attributes as identifying Oct 31, 2024
@pellared
Copy link
Member Author

pellared commented Oct 31, 2024

The idea is to add otel_scope_[attribute] and otel_scheme_url labels to metrics.

I will do my best to help with this issue.

@pellared
Copy link
Member Author

A prototype in Go: open-telemetry/opentelemetry-go#5947

@pellared
Copy link
Member Author

pellared commented Apr 29, 2025

Based on the prototype, I think this could be split into 4 sub-issues:

  1. Handle scheme URL as identifying
  2. Handle scope attributes as identifying
  3. Define a temporary env var (e.g. for 3 months) to control without_scope_info exporter configuration default value (initially false, later true) [Prometheus and OpenMetrics] Handle scheme URL and scope attributes as identifying #4223 (comment)
  4. Remove "without_scope_info" configuration (and remove scope_info)

@jsuereth
Copy link
Contributor

jsuereth commented Apr 29, 2025

This seems like the right path going forward. Now that these are all identifying, we CANNOT rely on joins for scope.

:EDIT: or if we did, we'd need some kind of "unique id" to perform a join based on all identifying attributes.

@pellared
Copy link
Member Author

@open-telemetry/prometheus-interoperability, @open-telemetry/collector-maintainers: PTAL

@jade-guiton-dd
Copy link
Contributor

jade-guiton-dd commented Apr 30, 2025

On the Collector side, I think there are no issues as long as the scope attribute set is 1. exposed to the user, and 2. identifying on the Prometheus side, to avoid errors with time series collisions. Adding the attributes as otel_scope_[attribute] labels on the metric points themselves as proposed above sounds like the simplest way to accomplish this.

(Unrelated, but what is the distinction between sub-issues 1 and 2 above?)

@pellared
Copy link
Member Author

pellared commented Apr 30, 2025

(Unrelated, but what is the distinction between sub-issues 1 and 2 above?)

@jade-guiton-dd

I have forgotten to delete "and scope attributes"` from sub-issue 1 😅 Fixed 😉

I will do my best to move this issue forward. However, I will start in about 2 weeks.

In the meantime you can try prototype it on the collector side and to test everything e2e together with open-telemetry/opentelemetry-go#5947 to make sure that there are not issues with this proposal. Having such e2e prototypes (Collector + Go) will help move the specification work forward.

@aknuds1
Copy link
Contributor

aknuds1 commented May 6, 2025

I made a corresponding Prometheus issue.

@jade-guiton-dd
Copy link
Contributor

@pellared By "prototyping on the Collector side", did you mean in the Prometheus exporter in collector-contrib? Based on the discussion in today's Collector SIG meeting, it sounds like this part in CONTRIBUTING.md would make this not "count" as a prototype for the purpose of changing the spec:

For this reason, when adding new features with Development maturity level, a prototype is defined as a working demonstration of the feature in a language implementation which has the support of that language's maintainers.

In other words, we may need a prototype in another language SDK's Prometheus exporter

@mx-psi
Copy link
Member

mx-psi commented May 7, 2025

Filed #4497 to reword the prototype requirement

@pellared
Copy link
Member Author

pellared commented May 7, 2025

@jade-guiton-dd, I think that Prometheus receiver in collector-contrib is also crucial (not only exporter).

@jade-guiton-dd
Copy link
Contributor

jade-guiton-dd commented May 7, 2025

Yes of course, everything performing translation between OTel and Prometheus will need to be updated eventually. I was just wondering about what prototypes you think need to be done to get the spec change moving.

Re-reading your message, I think I misunderstood. By "e2e prototypes (Collector + Go)", did you mean a single prototype where the draft PR modifying the SDK exporter is integrated into the Collector to test that it fixes our issue when producing scope attributes?

@pellared
Copy link
Member Author

pellared commented May 7, 2025

did you mean a single prototype where the draft PR modifying the SDK exporter is integrated into the Collector to test that it fixes our issue when producing scope attributes?

No. I just mean building 3 prototypes: Go SDK Prometheus exporter, Collector Prometheus receiver, Collector Prometheus exporter and check if they will work together correctly (even "manually"). I just think it would be nice to check all components starting from an instrumented application, through Collector, finishing in Prometheus. I am fine with any other validation/testing approach.

@pellared
Copy link
Member Author

pellared commented May 9, 2025

I updated the OTel Go's exporter implementation here: open-telemetry/opentelemetry-go#5947. PTAL

@ArthurSens
Copy link
Member

PoC for Prometheus exporter in collector-contrib: open-telemetry/opentelemetry-collector-contrib#40004

Reviews appreciated, especially in test coverage of edge cases :)

@pellared
Copy link
Member Author

@ArthurSens, are you going to also work on prototype for prometheusreceiver?

@pellared
Copy link
Member Author

Given open-telemetry/opentelemetry-collector-contrib#40004 (comment):

Turns out our exporter never exposed otel_scope_info, so this PR just introduces the addition of the new labels.

and https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/3c6a5ea6430afaac7c33a25ff276903ef829693b/receiver/prometheusreceiver#resource-and-scope:

It drops the otel_scope_info metric, and uses attributes (other than otel_scope_name and otel_scope_version) to populate Scope Attributes.

It looks like we can drop point 3 from #4223 (comment) completely (otel_scope_info metric is useless)

@ArthurSens
Copy link
Member

ArthurSens commented May 13, 2025

@ArthurSens, are you going to also work on prototype for prometheusreceiver?

I spent some time yesterday and it was not as easy as I expected, but I'm also not 100% familiar with that codebase 😬

I plan to spend more time on it this week, but it might take a while to have a PoC

@pellared
Copy link
Member Author

I created a specification PR. PTAL:

pellared added a commit to open-telemetry/opentelemetry-go that referenced this issue May 24, 2025
…ls (#5947)

Fixes #5846

Towards
open-telemetry/opentelemetry-specification#4223
(first two points from
open-telemetry/opentelemetry-specification#4223 (comment))

- Add instrumentation scope schema URL as `otel_scope_schema_url` label
to exported metrics
- Add instrumentation scope attributes as `otel_scope_[attribute]`
labels to exported metrics

Side notes:

- The exporter does not seem to work correctly if the end user adds e.g.
an `otel_scope_name` attribute. I think the exporter should ignore all
attributes with names that have prefix `otel_scope_`. This scenario is
also not covered by the spec. I think it may be covered by a separate PR
and issue.
- Removal of `otel_scope_info` metric would be handled as a separate PR.
#6770
@ArthurSens
Copy link
Member

pellared added a commit to open-telemetry/opentelemetry-go that referenced this issue May 28, 2025
Fixes #6768

Towards
open-telemetry/opentelemetry-specification#4223
(last point from from
open-telemetry/opentelemetry-specification#4223 (comment))

- Remove instrumentation scope attributes as `otel_scope_info` metric
songy23 pushed a commit to open-telemetry/opentelemetry-collector-contrib that referenced this issue May 29, 2025
…butes as labels (#40004)

#### Description
This PR is a PoC for the spec change described at
open-telemetry/opentelemetry-specification#4223

In the specification change, it's being proposed that Prometheus
exporters stop generating the metric `otel_scope_info` with all the
scope attributes and instead add all scope information as labels,
turning Scope information "identifying".

Turns out our exporter never exposed `otel_scope_info`, so this PR just
introduces the addition of the new labels.

---------

Signed-off-by: Arthur Silva Sens <[email protected]>
github-merge-queue bot pushed a commit that referenced this issue Jun 5, 2025
Fixes
#4223

Prototypes:
- open-telemetry/opentelemetry-go#5947
- open-telemetry/opentelemetry-go#6770
- open-telemetry/opentelemetry-java#7356
-
open-telemetry/opentelemetry-collector-contrib#40060
-
open-telemetry/opentelemetry-collector-contrib#40004



## Changes

Currently (before this PR) [Prometheus and OpenMetrics
Compatibility](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md)
assumes that only scope name and scope version are identifying.

However, with
#4161
this is no longer true.

Therefore, this PR updates the Prometheus and OpenMetrics Compatibility
specification to add the scope name, version, schema URL, scope
attributes to all metrics.

This also removes the `otel_scope_info` as it looks that it won't be
useful. See:
#4223 (comment).

This change important for Collector
open-telemetry/opentelemetry-go#5846 (comment).
It is also is necessary towards stabilization of OTel-Prom/OpenMetrics
compatibility) and the Prometheus exporter.

_Initially, I thought about [splitting it into a few
PRs](#4223 (comment)).
However, it looks like doing it in one PR would be a more complete
approach (also there are not that many changes)._

---------

Co-authored-by: Jade Guiton <[email protected]>
Co-authored-by: Carlos Alberto Cortez <[email protected]>
@github-project-automation github-project-automation bot moved this from Spec - Accepted to Spec - Closed in Specification + OTEPs Jun 5, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
sig-issue A specific SIG should look into this before discussing at the spec spec:metrics Related to the specification/metrics directory triage:accepted:ready Ready to be implemented. Small enough or uncontroversial enough to be implemented without sponsor
Projects
Status: Done
Status: Spec - Closed
Development

Successfully merging a pull request may close this issue.

8 participants