Telemetry Schemas and Semantic Convention Migration: OTCA practice questions

Semantic conventions change over time. Attributes get renamed, grouped into better namespaces or corrected, and every such change can break a dashboard or alert that looks for the old name. Telemetry schemas exist so that semantic conventions, the sources that emit telemetry and the consumers that read it can evolve independently without breaking each other.

A telemetry schema is versioned and identified by a Schema URL. The URL must point to a schema file that can actually be downloaded over HTTP or HTTPS, and the last segment of its path is the version number. Everything before that segment is the Schema Family identifier, so all versions of one schema share the same prefix. Published schema files never change, which means a consumer can cache them permanently or bundle them at build time. Version numbers follow MAJOR.MINOR.PATCH ordering rules borrowed from SemVer 2.0, and the OpenTelemetry schema version matches the semantic conventions release that publishes it, available under opentelemetry.io/schemas followed by the version.

A schema file is YAML. Its file_format field states the format version and has nothing to do with the schema version. The schema_url field must carry the highest version listed in the versions section. Each version lists changes in sections named all, resources, spans, span_events, metrics and logs, and the supported transformations are deliberately few, mainly renaming attributes, plus renaming events and metrics in their own sections. The all section is applied first, then the section for the data type being converted. Note that the 1.1.0 file format is still marked Development.

Telemetry carries its schema through OTLP. A schema_url field exists at the resource level and at the instrumentation scope level, and when both are set the scope value takes precedence for the data inside that scope. The API also lets instrumentation obtain a Tracer or Meter associated with a schema URL. In the Collector the debug exporter at detailed verbosity prints both values, which is a quick way to see which version a source emits.

Consumers that care about a particular version can translate. In the Collector, the contrib schema processor, currently alpha, takes a list of target schema URLs, one per family, fetches the schema files needed and rewrites incoming telemetry to the target version. By default it does hard renames, dropping the old attribute name. A migration entry with a target and a from version makes it write both names for a while so that queries can be updated first.

Instrumentation libraries have their own migration switch for the move from experimental to stable conventions. For HTTP, OpenTelemetry-published instrumentations should accept OTEL_SEMCONV_STABILITY_OPT_IN with http, which emits only the stable names such as http.request.method, or http/dup, which emits old and new names together. Without the variable they keep emitting the old conventions.