# semconv.com

> A version-by-version record of the OpenTelemetry semantic conventions, specification and OTLP: which attributes were renamed, which requirements appeared in a stable document, and which fields changed on the wire.

Derived from four OpenTelemetry repositories, all Apache-2.0 licensed: semantic-conventions,
opentelemetry-specification, opentelemetry-proto, and semantic-conventions-genai. Independent project, built by Maple.
Not affiliated with the OpenTelemetry project or the CNCF.

Currently tracking:
- Semantic conventions v1.30.0 to v1.44.0 - 940 attributes, 541 metrics, 97 known renames
- Specification v1.42.0 to v1.60.0 - 90 documents, 1753 RFC 2119 requirements
- OTLP v1.4.0 to v1.11.0 - 72 wire definitions plus the protocol requirements
- GenAI conventions at 2026-09-03 - 82 attributes. UNRELEASED: that repository has never cut a
  tag, so it is tracked from its default branch and dated rather than versioned, and everything in
  it is development stability.

## Answering the three common questions

**"Is this attribute name still current?"**
Fetch https://semconv.com/api/renames.json - every deprecated attribute with the name that replaced it and
the release that did it. Small enough to hold in context while auditing a codebase. An id absent
from that list is either current or was deprecated without a successor;
https://semconv.com/api/attributes.json distinguishes the two via each entry's `deprecated` field.

Mind the third case: v1.44.0 moved the entire `gen_ai.*` namespace out to the GenAI conventions
repository. Those attributes appear in semantic-conventions as deprecated "Moved to..." stubs while
their live definitions sit in the other registry, so a check that reads only semantic-conventions
reports ~59 attributes in active production use as dead. `/api/attributes.json` serves both
registries, each entry tagged with `registry`, and `check_attribute_names` returns status
`moved` for these - meaning current, no code change needed.

**"What changed between the version we targeted and now?"**
Fetch https://semconv.com/api/diff/{source}/{from}...{to}.json for any ordered pair of tracked versions of
any source, e.g. https://semconv.com/api/diff/semconv/1.30.0...1.44.0.json.
Each change carries `kind`, `severity`, `entity`, `id`, `detail`, and `renamedTo` where a
successor is known.

**"What is involved in instrumenting X?"**
Fetch https://semconv.com/api/domains.json - the registry grouped by topic. Attributes, metrics and signals
carry the same namespace prefixes, so a domain gathers all three; `governedBy` names the parts of
the specification that bind each signal kind. The specification prose never says "database", which
is why a keyword search of it comes back empty: what binds a db span is the trace specification.

**"What does the spec actually require here?"**
Fetch https://semconv.com/api/requirements.json - every MUST, SHOULD and MAY in the current specification and
in the OTLP protocol document, each with its section and that document's stability status. Note
that the OTLP protocol specification is NOT in the specification repository: it lives in
`docs/specification.md` of opentelemetry-proto, and `specification/protocol/otlp.md` is a stub
that redirects to the website. Both are covered here.

## MCP

https://semconv.com/mcp is a public, read-only MCP server (streamable HTTP, no auth, no session state).
Tools: list_versions, check_attribute_names, get_attribute, search_attributes, diff_versions,
search_requirements, get_otlp_message.
check_attribute_names takes the attribute keys a codebase emits and reports which are deprecated,
renamed, or absent from the registry - use it instead of answering from training data.

## Endpoints

- https://semconv.com/api/domains.json - the conventions grouped by topic: every namespace, metric and signal a
  domain owns, plus the specification areas that bind them. Upstream publishes no such grouping
- https://semconv.com/api/search.json - one index over everything: attributes, metrics, signals, requirements
  and OTLP messages, each with a type and a URL
- https://semconv.com/api/versions.json - every tracked release of all three sources, with change counts
- https://semconv.com/api/attributes.json - every semantic-conventions attribute at v1.44.0
- https://semconv.com/api/attributes/{id}.json - one attribute in full, plus its release-by-release history
- https://semconv.com/api/renames.json - deprecated attribute name to successor name
- https://semconv.com/api/requirements.json - every RFC 2119 requirement in the spec and in OTLP
- https://semconv.com/api/otlp.json - OTLP messages, fields, field numbers and enum values
- https://semconv.com/api/diff/{source}/{from}...{to}.json - changes between any two tracked versions
- https://semconv.com/feed.xml - RSS, one entry per release across all three sources

## Pages

- https://semconv.com/ - release history across all three sources, newest first
- https://semconv.com/domains - the conventions by topic: databases, HTTP, messaging, Kubernetes, GenAI, ...
- https://semconv.com/domains/{slug} - one topic in full: its attributes, metrics, spans, events and the
  specification requirements that govern them
- https://semconv.com/search - search attributes, metrics, signals, requirements and OTLP messages at once
- https://semconv.com/attributes - the semantic-conventions registry, grouped by namespace and filterable
- https://semconv.com/attributes/{id} - one attribute, its definition, its usage, and its history
- https://semconv.com/spec - specification documents and their requirements
- https://semconv.com/otlp - the OTLP wire definitions
- https://semconv.com/releases/{source}/{version} - everything that changed in one release
- https://semconv.com/diff - compare any two versions
- https://semconv.com/about - how the data is produced, and what it does not cover

## How to read `severity`

- `breaking` - for semantic conventions, removes or renames something already marked stable or
  release candidate; for the specification, adds, drops or restrengthens a requirement in a
  document marked Stable; for OTLP, changes an existing field in a released (non-development)
  package. Both OTLP encodings are load-bearing: binary keys on the field number, JSON keys on the
  field name, so a rename breaks JSON clients even though the binary format never notices.
- `notable` - the same class of change on a development-stability definition. Expected churn,
  but it will still move data.
- `informational` - wording, examples and guidance. No effect on emitted telemetry.

Upstream release notes use their own categories and the two do not always agree; both are shown
on each release page.

## Caveats worth passing on

- History starts at semconv v1.30.0, spec v1.42.0, OTLP
  v1.4.0. Anything reported as first seen there may be considerably older.
- Deprecated attributes remain in the registry. A deprecated name still resolves, so a consumer
  usually has to read both the old and new spelling until instrumentation catches up.
- Specification changes are tracked as RFC 2119 requirements, not as prose diffs. A paragraph
  rewritten without changing what it requires will show as editorial.
- Only `specification/` is read from the specification repository. `oteps/`, `development/` and
  `supplementary-guidelines/` are proposals and commentary, and their MUSTs do not bind anyone.