Semantic Conventions
In opentelemetry, a semantic convention is a standard name and shape for a piece of telemetry — what field an HTTP request's method goes in, what a database call's target should be called — so that "completely separate authors can instrument different libraries, in different languages, and still produce telemetry that follows the same contract." An HTTP request looks like an HTTP request no matter which library emitted it, which is what lets a user build one dashboard or query across instrumentation nobody coordinated directly. Introduced to this spoke via exploring-instrumentation-ecosystem.
The gap this page exists to name
A convention reaching stable status is "more of a starting point rather than a finish line." Publishing the spec does not update any library's code — that is separate, uncoordinated work by every language's maintainers, and it can take years after the spec stabilizes:
- HTTP: proposed June 2019, stable November 2023.
- Database: proposed May 2019, stable May 2025.
Even after a library adopts a stable convention, measured conformance can still show gaps — the OpenTelemetry Java agent had HTTP attribute gaps found after it had already adopted the stable HTTP conventions in its own 2.0 release. Attributes also come in two strengths, required and recommended, and the first cross-language audit found required attributes present almost everywhere and recommended ones present far less often — the split in the spec anticipates exactly the gap now being measured instead of assumed.
Why this matters for the spoke
This is the same "seams, not components" thesis the spoke's synthesis already runs on Kubernetes's CNCF tools and service meshes, applied one level lower: opentelemetry is presented elsewhere in this spoke as the standardized instrumentation layer that lets telemetry "line up" across tools — semantic conventions are the literal mechanism that promise does — and this page records that the promise itself has an adoption lag, not just an integration cost between finished tools.
Related
opentelemetry · otel-ecosystem-explorer · exploring-instrumentation-ecosystem · distributed-tracing · otel-observability-primer