OpenTelemetry Semantic Conventions
This skill governs correct selection, placement, and validation of telemetry attributes and metric instruments according to the OpenTelemetry Semantic Conventions specification.
For span naming, span kinds, and span status codes, see the otel-instrumentation skill.
The Attribute Registry is the single source of truth for all defined attributes.
Rules
| Rule |
Description |
Use Case |
| attributes |
Attribute registry, selection, placement, common attributes by domain |
Choosing or reviewing attributes; HTTP/DB/messaging/RPC attributes; attribute placement (resource vs span) |
| versioning |
Semconv versioning, stability, migration |
Semconv version migration |
| dash0 |
Dash0 derived attributes and feature dependencies |
Dash0 derived attributes |
Official documentation
How to select the right attribute
- Search the registry first — Look up the concept in the Attribute Registry. Use the standard name if it exists (e.g., prefer
http.request.method over a custom custom.http.verb). Custom names fragment querying and break tooling — only create a custom attribute when no registry entry covers the concept.
- Check stability — Prefer
stable attributes; note any experimental attributes that may change. See versioning.
- Place at the correct level — Resource attributes describe the entity producing telemetry; span/log attributes describe the individual operation. Do not duplicate across levels. Once an attribute is at a given level, keep it there consistently across all services.
- Verify cardinality — Metric attribute values must be low-cardinality (bounded set). Variable data (user IDs, request paths with parameters) belongs in span attributes, not metric attributes.
- Custom attribute as last resort — Only create a custom attribute if no registry entry covers the concept. Document the decision and follow the
org.namespace.attribute_name naming pattern.
Example: correct vs incorrect attribute selection
# Correct — uses registry attribute for HTTP method
span.set_attribute("http.request.method", "GET")
# Incorrect — invents a custom attribute for a concept already in the registry
span.set_attribute("custom.http.verb", "GET")
Example: resource vs span attribute placement
# Correct — service identity is a resource attribute
resource = Resource({"service.name": "checkout-service", "service.version": "2.1.0"})
# Correct — operation-specific data is a span attribute
span.set_attribute("http.request.method", "POST")
span.set_attribute("http.response.status_code", 201)
# Incorrect — placing a resource-level attribute on every span
span.set_attribute("service.name", "checkout-service") # belongs on the resource
Example: cardinality violation in metric attributes
# Correct — metric attribute uses a bounded, low-cardinality value
histogram.record(duration_ms, {"http.request.method": "GET", "http.response.status_code": 200})
# Incorrect — unbounded values as metric attributes explode storage and query cost
histogram.record(duration_ms, {"user.id": "u-839201", "url.path": "/orders/839201"})
# Fix: move high-cardinality values to span attributes instead
span.set_attribute("user.id", "u-839201")
span.set_attribute("url.path", "/orders/839201")
1---2name: otel-semantic-conventions3description: OpenTelemetry Semantic Conventions expert. Use when selecting, applying, or reviewing telemetry attributes. Triggers on tasks involving attribute selection, semantic convention compliance, attribute migration, or custom attribute decisions. Covers the attribute registry, naming patterns, attribute placement, and versioning. For span names, span kinds, and span status codes, see the otel-instrumentation skill.4---5
6# OpenTelemetry Semantic Conventions
7
8This skill governs correct selection, placement, and validation of telemetry attributes and metric instruments according to the OpenTelemetry Semantic Conventions specification.
9For span naming, span kinds, and span status codes, see the [otel-instrumentation](../otel-instrumentation/) skill.
10
11The [Attribute Registry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/) is the single source of truth for all defined attributes.
12
13## Rules
14
15| Rule | Description | Use Case |
16|-------------------------------------|-----------------------------------------------------------------------|-----------------------------------------------------------------|
17| [attributes](./rules/attributes.md) | Attribute registry, selection, placement, common attributes by domain | Choosing or reviewing attributes; HTTP/DB/messaging/RPC attributes; attribute placement (resource vs span) |
18| [versioning](./rules/versioning.md) | Semconv versioning, stability, migration | Semconv version migration |
19| [dash0](./rules/dash0.md) | Dash0 derived attributes and feature dependencies | Dash0 derived attributes |
20
21## Official documentation
22
23- [Attribute Registry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/)
24- [Semantic Conventions Specification](https://opentelemetry.io/docs/specs/semconv/)
25- [Semantic Conventions Repository](https://github.com/open-telemetry/semantic-conventions)
26- [Dash0 Semantic Conventions](https://www.dash0.com/documentation/dash0/semantic-conventions)
27- [Dash0 Semantic Conventions Explainer](https://www.dash0.com/knowledge/otel-semantic-conventions-explainer)
28
29## How to select the right attribute
30
311. **Search the registry first** — Look up the concept in the [Attribute Registry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/). Use the standard name if it exists (e.g., prefer `http.request.method` over a custom `custom.http.verb`). Custom names fragment querying and break tooling — only create a custom attribute when no registry entry covers the concept.
322. **Check stability** — Prefer `stable` attributes; note any `experimental` attributes that may change. See [versioning](./rules/versioning.md).
333. **Place at the correct level** — Resource attributes describe the entity producing telemetry; span/log attributes describe the individual operation. Do not duplicate across levels. Once an attribute is at a given level, keep it there consistently across all services.
344. **Verify cardinality** — Metric attribute values must be low-cardinality (bounded set). Variable data (user IDs, request paths with parameters) belongs in span attributes, not metric attributes.
355. **Custom attribute as last resort** — Only create a custom attribute if no registry entry covers the concept. Document the decision and follow the `org.namespace.attribute_name` naming pattern.
36
37### Example: correct vs incorrect attribute selection
38
39<!-- eval:skip -->
40```
41# Correct — uses registry attribute for HTTP method
42span.set_attribute("http.request.method", "GET")
43
44# Incorrect — invents a custom attribute for a concept already in the registry
45span.set_attribute("custom.http.verb", "GET")
46```
47
48### Example: resource vs span attribute placement
49
50<!-- eval:skip -->
51```
52# Correct — service identity is a resource attribute
53resource = Resource({"service.name": "checkout-service", "service.version": "2.1.0"})
54
55# Correct — operation-specific data is a span attribute
56span.set_attribute("http.request.method", "POST")
57span.set_attribute("http.response.status_code", 201)
58
59# Incorrect — placing a resource-level attribute on every span
60span.set_attribute("service.name", "checkout-service") # belongs on the resource
61```
62
63### Example: cardinality violation in metric attributes
64
65<!-- eval:skip -->
66```
67# Correct — metric attribute uses a bounded, low-cardinality value
68histogram.record(duration_ms, {"http.request.method": "GET", "http.response.status_code": 200})
69
70# Incorrect — unbounded values as metric attributes explode storage and query cost
71histogram.record(duration_ms, {"user.id": "u-839201", "url.path": "/orders/839201"})
72# Fix: move high-cardinality values to span attributes instead
73span.set_attribute("user.id", "u-839201")
74span.set_attribute("url.path", "/orders/839201")
75```
dash0hq