otel-semantic-conventions
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.
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 |