This gap was surfaced by @dashpole while reviewing #5135 (SDK self-observability supplementary guidelines): there is no spec-level guideline for instrumentation library authors. Once such guidelines land, the SDK self-observability supplementary guidelines can simply reference them rather than restating provider-acquisition patterns inline.
What already exists in the spec
Only naming conventions (overview.md), a glossary definition, and metrics-only instrument-selection guidance. The website concept page exists but is non-normative.
What individual languages already document
Each major language has independently developed guidance: .NET, Go contrib, Java instrumentation, and Python contrib. The Go contrib doc even uses normative MUST/SHOULD language.
Common topics across these documents
Independently developed, but overlapping:
- How to obtain
TracerProvider / MeterProvider / LoggerProvider (the "accept explicit, fall back to global" pattern is explicit in both .NET and Go).
- Whether instrumentation should accept the provider vs. the Tracer/Meter directly (Go says MUST accept provider, MUST NOT accept tracer/meter — this is a strong shared convention).
- Naming and versioning the
InstrumentationScope / ScopeName.
- Participation in context propagation (when to inject/extract).
- Dependency policy (API-only vs. SDK).
- Error recording conventions across signals.
- Stability expectations.
- Configuration surface conventions (enable/disable, experimental signals, etc.).
The fact that each language has independently produced guidance on the same topics suggests that a cross-language baseline could reduce divergence and make instrumentation behavior more predictable across the ecosystem.
cc @dashpole
This gap was surfaced by @dashpole while reviewing #5135 (SDK self-observability supplementary guidelines): there is no spec-level guideline for instrumentation library authors. Once such guidelines land, the SDK self-observability supplementary guidelines can simply reference them rather than restating provider-acquisition patterns inline.
What already exists in the spec
Only naming conventions (
overview.md), a glossary definition, and metrics-only instrument-selection guidance. The website concept page exists but is non-normative.What individual languages already document
Each major language has independently developed guidance: .NET, Go contrib, Java instrumentation, and Python contrib. The Go contrib doc even uses normative MUST/SHOULD language.
Common topics across these documents
Independently developed, but overlapping:
TracerProvider/MeterProvider/LoggerProvider(the "accept explicit, fall back to global" pattern is explicit in both .NET and Go).InstrumentationScope/ScopeName.The fact that each language has independently produced guidance on the same topics suggests that a cross-language baseline could reduce divergence and make instrumentation behavior more predictable across the ecosystem.
cc @dashpole