About

OpenTelemetry is four separately-versioned repositories, and each one has to be read differently. This site reads all of them at every release and turns the result into pages you can link to.

Three sources, three methods

Semantic conventions ship a machine-readable registry in which every attribute carries a stability level and, when deprecated, the name of whatever replaced it. That makes them diffable directly.

The specification is prose, so it is indexed by the only part that binds an implementation: its RFC 2119 requirements. Each MUST, SHOULD and MAY is extracted and identified by a hash of its text, which is what separates a new requirement from a reflowed paragraph. Requirements that move between sections are matched across, so splitting a section does not read as dropping everything in it.

OTLP is parsed from the .proto files themselves — messages, field numbers, types, cardinality, enum values and retired numbers. The protocol prose is tracked alongside them, because it is not in the specification repository: specification/protocol/otlp.md is a stub that redirects to the website, and the real document lives in docs/specification.md of the proto repository.

The GenAI conventions are the same registry model in a separate repository, split out of the conventions in v1.44.0. That repository has never cut a release — no tags, a changelog reading only "Unreleased" — so it is tracked from its default branch, dated rather than versioned, and marked unreleased everywhere it appears.

The split leaves roughly 59 attributes in both registries at once: deprecated “Moved to…” stubs in the semantic conventions, live definitions in GenAI. Reading only the first registry would report attributes in daily production use as dead, so both are read and those are shown as moved rather than deprecated.

How it is built

Every tagged release is downloaded, normalized into a flat snapshot, and committed. The site builds from those committed snapshots with no network access, so a page can always be reproduced from the repository alone. A scheduled job checks for new releases and opens a pull request when it finds one.

The conventions are mid-migration between two model file formats. Both are read. This matters more than it sounds: v1.44.0 moved server.*,client.* and everyhw.* metric to the newer format, and a reader that understood only the older one would report all of them as deleted from the registry.

What "breaking" means here

For the conventions: removing, renaming or walking back something already marked stable or release‑candidate — the tier where the project promises not to do that. For the specification: adding, dropping or restrengthening a requirement in a document marked Stable. For OTLP: changing an existing field in a released package. The same changes to a development-stability definition are marked notable instead, because churn there is expected and flagging it as breaking would drown the signal.

Both OTLP encodings are load-bearing, which is why nearly any change to an existing field counts: binary OTLP keys on the field number, OTLP/JSON keys on the fieldname. Renaming a field breaks every JSON client even though the binary format never notices.

Upstream release notes use their own categories; both are shown, and they do not always agree.

Limits

• History starts at semantic conventions v1.30.0, specification v1.42.0 and OTLP v1.4.0. Anything described as first seen there may be much older. The GenAI registry has no history at all yet — tracking began 2026-09-03.
• Specification changes are tracked as requirements, not as prose diffs. A paragraph rewritten without changing what it requires shows as editorial.
• Only specification/ is read from the specification repository. oteps/, development/ and supplementary-guidelines/ are proposals and commentary, and their MUSTs bind no one.
• Definitions are reported as the registry states them. Where the registry is silent, so is this site.

For agents

Every page has a machine-readable counterpart. See llms.txt for the map, or fetch /api/attributes.jsondirectly.

There is also a public, read-only MCP server at/mcp — no auth, no session state. Its most useful tools are check_attribute_names, which takes the attribute keys a codebase emits and reports which are deprecated, renamed, or not in the registry at all, and search_requirements, which searches every MUST and SHOULD in the specification and in OTLP. Both are worth reaching for before asserting what is current, since these repositories move monthly and a model's training data usually does not.

Independent project, built by Maple. Not affiliated with the OpenTelemetry project, the CNCF, or the Linux Foundation. Source data is © the OpenTelemetry Authors, licensed Apache 2.0.