otel-semantic-conventions

name	otel-semantic-conventions
description	OpenTelemetry Semantic Conventions expert. Use when selecting, applying, or reviewing telemetry attributes, span names, span kinds, or span status codes. Triggers on tasks involving attribute selection, naming telemetry, semantic convention compliance, attribute migration, or custom attribute decisions. Covers the attribute registry, naming patterns, status mapping, attribute placement, and versioning.
metadata	{"author":"dash0","version":"1.0.0"}

OpenTelemetry Semantic Conventions

Semantic conventions define standardized names, types, and semantics for telemetry attributes, span names, metric instruments, and log fields. They ensure that telemetry from different libraries, frameworks, and services describes the same concepts in the same way — enabling correlation, querying, and tooling across the entire stack.

The Attribute Registry is the single source of truth for all defined attributes.

Rules

Rule	Description
attributes	Attribute registry, selection, placement, common attributes by domain
versioning	Semconv versioning, stability, migration
dash0	Dash0 derived attributes and feature dependencies

Official documentation

• Attribute Registry
• Semantic Conventions Specification
• Semantic Conventions Repository
• Dash0 Semantic Conventions
• Dash0 Semantic Conventions Explainer

Key principles

• Registry first — Search the Attribute Registry before creating any custom attribute
• No custom attributes unless necessary — Custom names fragment querying and break tooling
• Low cardinality in names — Span names and metric attribute values must be bounded; variable data goes in attributes
• Right level, every time — Place attributes at the correct telemetry level (resource, scope, span, log, metric)
• Consistent placement — Once an attribute is at a level, keep it there across all services

Quick reference

Use Case	Rule
Choosing or reviewing attributes	attributes
HTTP/DB/messaging/RPC attributes	attributes
Attribute placement (resource vs span)	attributes
Naming a span or choosing span kind	spans
Span status code mapping	spans
Semconv version migration	versioning
Dash0 derived attributes	dash0