Skip to content

Add supplementary guidelines for SDK self-observability #5128

Description

@cijothomas

Follow-up to #5087, which introduced specification/self-observability.md.

The current document is intentionally minimal. Based on feedback from the spec community meeting (2026-06-02), implementations would benefit from non-normative supplementary guidelines covering:

  • Lifecycle and ordering — how to handle telemetry emitted before the recording provider is initialized (buffering, throwaway/bootstrap loggers) and the symmetric shutdown case.
  • Avoiding telemetry-induced-telemetry loops — recommended patterns to prevent the SDK from recursively instrumenting its own export pipeline.
  • Startup configuration event — emitting a single verbose event/log on SDK init with the resolved effective configuration (env vars, exporters, processors, detected resource) to aid debugging.
  • Scope of signals — clarifying that self-observability is metrics-focused today but may extend to logs/traces; designing for that.
  • Telemetry versioning — guidance on schema URLs and handling stability transitions for self-observability telemetry.
  • Opt-in / performance — patterns used by existing SDKs (e.g., Go's OTEL_GO_X_OBSERVABILITY, Java's configuration toggle).

Proposed location: specification/self-observability-supplementary-guidelines.md, following the pattern of specification/{logs,metrics,configuration}/supplementary-guidelines.md.

Metadata

Metadata

Assignees

Labels

area:error-reportingRelated to error reportingarea:sdkRelated to the SDKmaintainer-requestEscalated by SIG maintainerstriage:deciding:community-feedbackOpen to community discussion. If the community can provide sufficient reasoning, it may be accepted

Type

No type

Fields

No fields configured for issues without a type.

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions