Skip to content

Reference semantic conventions for SDK self-observability metrics#5087

Merged
reyang merged 3 commits into
open-telemetry:mainfrom
cijothomas:sdk-self-observability-metrics-link
Jun 2, 2026
Merged

Reference semantic conventions for SDK self-observability metrics#5087
reyang merged 3 commits into
open-telemetry:mainfrom
cijothomas:sdk-self-observability-metrics-link

Conversation

@cijothomas

@cijothomas cijothomas commented May 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Adds an in-development Self-Observability.md document and SDK-level Self-observability sections in the Tracing and Logs and Metrics SDK specs that point to it. The Self-Observability document defers to the OpenTelemetry semantic conventions for SDK self-observability metric names, attributes, and values.

This is step 1 of defining self-observability as part of the spec itself; follow-ups can extend it (e.g., exporter metrics, reader metrics, self-logs, self-events) under the same umbrella.

Companion PR in semantic-conventions reserving the error.type values (queue_full, already_shutdown): open-telemetry/semantic-conventions#3710.

Resolves #5086.

@cijothomas
cijothomas marked this pull request as ready for review May 11, 2026 20:17
@cijothomas
cijothomas requested review from a team as code owners May 11, 2026 20:17
@cijothomas
cijothomas force-pushed the sdk-self-observability-metrics-link branch from 52ce704 to 1221b00 Compare May 11, 2026 23:44
@cijothomas

cijothomas commented May 12, 2026

Copy link
Copy Markdown
Member Author

Thanks for discussing this in SIG Call.
@jsuereth Agreed to point to the website instead of main commit.
@lmolkova I started with a dedicated doc and then scoped down to this approach to get some directional alignment. Given general support on direction, lets review this PR as-is, and I can take care of moving to a dedicated self-observability doc. (I am also eager to see it covering internal Events (log with name))

@tigrannajaryan The PR desc has a "note for reviewers" - Let me know if that address your concern about spec trying to list what sem-conv should be covering.

dashpole
dashpole reviewed May 12, 2026
View reviewed changes
Comment thread specification/semantic-conventions.md Outdated
lmolkova
lmolkova reviewed May 12, 2026
View reviewed changes

@lmolkova lmolkova left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM directionally with a small caveat on moving / linking it from current self-diagnostics section

Comment thread specification/semantic-conventions.md Outdated
Comment thread specification/semantic-conventions.md Outdated
@cijothomas cijothomas mentioned this pull request May 12, 2026
Open
dashpole
dashpole reviewed May 13, 2026
View reviewed changes

@dashpole dashpole left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you want to cover the other SDK components (e.g. simple {signal} processors, or the trace SDK (spans started/live), or log sdk (logs created).

There are also the span/log/metric exporter metrics, which it wold be nice to have on the corresponding OTLP exporters.

Comment thread specification/trace/sdk.md Outdated
@cijothomas

cijothomas commented May 15, 2026

Copy link
Copy Markdown
Member Author

Do you want to cover the other SDK components (e.g. simple {signal} processors, or the trace SDK (spans started/live), or log sdk (logs created).

There are also the span/log/metric exporter metrics, which it wold be nice to have on the corresponding OTLP exporters.

Great points — fully agree these all deserve coverage. I'd like to keep this PR scoped as a first step to lock in directional acceptance: spec treats self-observability as a first-class concern and points to semantic conventions as the source of truth for metric names, attributes, and values. Once this PR is merged, I can follow up with rest of the metrics.

peschinskiy
peschinskiy reviewed May 15, 2026
View reviewed changes
Comment thread specification/logs/sdk.md Outdated
@cijothomas
cijothomas requested a review from lmolkova May 15, 2026 15:44
jack-berg
jack-berg reviewed May 15, 2026
View reviewed changes
Comment thread specification/logs/sdk.md Outdated
@cijothomas cijothomas mentioned this pull request May 26, 2026
Merged
cijothomas added a commit to cijothomas/opentelemetry-specification that referenced this pull request May 26, 2026
@cijothomas
Reference PR open-telemetry#5087 instead of issue open-telemetry#5086 …
935a891 
…in CHANGELOG entries
pellared
pellared reviewed May 27, 2026
View reviewed changes
Comment thread specification/logs/sdk.md Outdated
@cijothomas

cijothomas commented Jun 1, 2026

Copy link
Copy Markdown
Member Author

@dashpole Given I have refactored significantly after your approval, could you re-review please?

pellared
pellared approved these changes Jun 2, 2026
View reviewed changes

@pellared pellared left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about also adding The Metrics SDK SHOULD support [SDK self-observability](../self-observability.md). for completeness?

Comment thread specification/self-observability.md Outdated
reyang
reyang reviewed Jun 2, 2026
View reviewed changes
Comment thread CHANGELOG.md Outdated
pellared
pellared reviewed Jun 2, 2026
View reviewed changes
Comment thread CHANGELOG.md Outdated
@pellared
pellared requested review from jack-berg and peschinskiy June 2, 2026 15:41
dashpole
dashpole approved these changes Jun 2, 2026
View reviewed changes
Comment thread specification/self-observability.md Outdated
@cijothomas
Add in-development SDK self-observability section
146fa38 
Adds a new specification/self-observability.md document defining
SDK self-observability at the spec level, and adds a one-line
Self-observability section to the Tracing, Metrics, and Logs SDK
specs pointing to it. Also references it from error-handling.md
and the top-level README.
@cijothomas
cijothomas force-pushed the sdk-self-observability-metrics-link branch from 14fd15e to 146fa38 Compare June 2, 2026 15:53
@cijothomas @dashpole
Apply suggestion from @dashpole
03a9db5 
Co-authored-by: David Ashpole <dashpole@google.com>
@reyang
reyang enabled auto-merge June 2, 2026 16:13
@cijothomas cijothomas mentioned this pull request Jun 2, 2026
Open
@reyang
reyang added this pull request to the merge queue Jun 2, 2026
Merged via the queue into open-telemetry:main with commit 2daeb9b Jun 2, 2026
9 checks passed
@cijothomas
cijothomas deleted the sdk-self-observability-metrics-link branch June 2, 2026 16:46
This was referenced Jun 2, 2026
Closed
Merged
dashpole added a commit to dashpole/opentelemetry-specification that referenced this pull request Jun 8, 2026
@cijothomas @dashpole
Reference semantic conventions for SDK self-observability metrics (op…
bae30ac 
…en-telemetry#5087)

Adds an in-development Self-Observability.md document and SDK-level
Self-observability sections in the Tracing and Logs SDK specs that point
to it. The Self-Observability document defers to the OpenTelemetry
semantic conventions for SDK self-observability metric names,
attributes, and values.

This is step 1 of defining self-observability as part of the spec
itself; follow-ups can extend it (e.g., exporter metrics, reader
metrics, self-logs, self-events) under the same umbrella.

Companion PR in semantic-conventions reserving the `error.type` values
(`queue_full`, `already_shutdown`):
open-telemetry/semantic-conventions#3710.

Resolves open-telemetry#5086.

---------

Co-authored-by: David Ashpole <dashpole@google.com>
@carlosalberto carlosalberto mentioned this pull request Jun 18, 2026
Merged
jack-berg pushed a commit to cijothomas/opentelemetry-specification that referenced this pull request Jun 22, 2026
@carlosalberto @reyang
Release 1.58.0 (open-telemetry#5164)
cf2668e 
### Context

- Clarify that environment variable propagation carriers normalize
requested
  keys, carrier keys, and returned keys.

([open-telemetry#5102](open-telemetry#5102))
- Specify that environment variable propagation carriers only read and
return
  normalized environment variable names.

([open-telemetry#5144](open-telemetry#5144))
- Specify that an empty environment variable propagation name is
non-normalized
  and normalizes to `_`.

([open-telemetry#5163](open-telemetry#5163))

### Profiles

- Remove duplicate information from and extend Profiles documentation
(README.md, pprof.md).

([open-telemetry#4932](open-telemetry#4932))

### Entities

- Add specification for communicating entity information as structured
log events.

([open-telemetry#4836](open-telemetry#4836))

### Common

- Add an in-development [SDK
self-observability](specification/self-observability.md)
  section, referenced from the Tracing, Metrics, and Logs SDK specs.

([open-telemetry#5087](open-telemetry#5087))
- Clarify non-OTLP representation guidance for nested `AnyValue` values
in
  arrays and maps.

([open-telemetry#5053](open-telemetry#5053))
- Add in-development guidance recommending a JSON object as the string
  representation for an attribute in non-OTLP protocols.

([open-telemetry#5028](open-telemetry#5028))
- Add in-development guidance recommending a JSON object as the string
  representation for an attribute collection in non-OTLP protocols.

([open-telemetry#5110](open-telemetry#5110))

### Compatibility

- Deprecate OpenCensus compatibility requirements in the specification.

([open-telemetry#5138](open-telemetry#5138))
- Stabilize sections of Prometheus Metrics Exporter.
  - Clarify resource attributes configuration.

([open-telemetry#5084](open-telemetry#5084))
- Stabilize the conversion of OTLP Summaries into Prometheus Summaries.

([open-telemetry#5107](open-telemetry#5107))
  - Stabilize client libs section.

([open-telemetry#5106](open-telemetry#5106))
- Stabilize Prometheus Metrics Exporter default aggregation
configuration.

([open-telemetry#5113](open-telemetry#5113))
- Stabilize sections of Prometheus and OpenMetrics Compatibility.
- Stabilize OpenTelemetry Histogram to Prometheus Histogram
transformation.

([open-telemetry#5091](open-telemetry#5091))
- Add optional OpenTelemetry Histogram to Prometheus Native Histogram
with Custom Buckets transformation.

([open-telemetry#5091](open-telemetry#5091))

### SDK Configuration

- Add link to declarative config IdGenerator type

([open-telemetry#5133](open-telemetry#5133))

### OTEPs

- Context-scoped Attributes.

([open-telemetry#4931](open-telemetry#4931))

---------

Co-authored-by: Reiley Yang <reyang@microsoft.com>
pull Bot pushed a commit to CodeWeaver13/opentelemetry-specification that referenced this pull request Jun 22, 2026
@cijothomas @pellared @jack-berg
Add supplementary guidelines for SDK self-observability (open-telemet…
94e3fc3 
…ry#5135)

Adds non-normative supplementary guidelines covering lifecycle ordering,
avoiding telemetry-induced-telemetry loops, and stability handling for
SDK self-observability.

Towards open-telemetry#5128. Follow-up to open-telemetry#5087.

---------

Co-authored-by: Robert Pająk <pellared@hotmail.com>
Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pellared pellared pellared approved these changes
@reyang reyang reyang approved these changes
@trask trask trask approved these changes
@carlosalberto carlosalberto carlosalberto approved these changes
@bogdandrutu bogdandrutu bogdandrutu approved these changes
@lmolkova lmolkova lmolkova approved these changes
@dashpole dashpole dashpole approved these changes
@jack-berg jack-berg jack-berg approved these changes
@peschinskiy peschinskiy Awaiting requested review from peschinskiy

Assignees

@lmolkova lmolkova

Labels

None yet

Projects

OTel Clients Self Observability
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

SDK spec does not reference self-observability metrics defined in semantic conventions

10 participants

@cijothomas @trask @carlosalberto @bogdandrutu @lmolkova @dashpole @pellared @peschinskiy @reyang @jack-berg