Skip to content

sb-dev/openquant / .agents/skills/otel-semantic-conventions

otel-semantic-conventions

Verified

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.

FileKindSize
SKILL.mdskill md5.0 KB
rules/attributes.mdmarkdown14.1 KB
rules/dash0.mdmarkdown5.8 KB
rules/versioning.mdmarkdown3.3 KB

rules/versioning.md

View on GitHub
---
title: "Versioning, Stability, and Migration"
impact: MEDIUM
tags:
  - versioning
  - migration
  - stability
  - semconv-upgrades
---

# Versioning

Use the rename table below when writing or reviewing attribute names.
Always use the current (new) name — not the deprecated one.
If you encounter a deprecated name in existing code, replace it with the current name.

## Stability levels

| Level | Meaning |
|---|---|
| **Stable** | Will not change in breaking ways. Safe to depend on. |
| **Experimental** | May change or be removed. Use with caution. |
| **Deprecated** | Replaced by a newer attribute. Migrate away. |

Always use stable attributes.
Only use experimental attributes when no stable alternative exists, and add a code comment noting the attribute is experimental so it can be updated when it stabilizes.

## Key renames to know

| Old Name | New Name |
|---|---|
| `http.method` | `http.request.method` |
| `http.status_code` | `http.response.status_code` |
| `http.url` | `url.full` |
| `http.target` | `url.path` + `url.query` |
| `http.scheme` | `url.scheme` |
| `http.flavor` | `network.protocol.version` |
| `http.user_agent` | `user_agent.original` |
| `http.client_ip` | `client.address` |
| `net.peer.name` | `server.address` |
| `net.peer.port` | `server.port` |
| `net.host.name` | `server.address` |
| `net.host.port` | `server.port` |
| `db.system` | `db.system.name` |
| `db.name` | `db.namespace` |
| `db.statement` | `db.query.text` |
| `db.operation` | `db.operation.name` |
| `deployment.environment` | `deployment.environment.name` |
| `http.server.duration` | `http.server.request.duration` (unit: ms → s) |
| `http.client.duration` | `http.client.request.duration` (unit: ms → s) |

For the full list of attribute changes, see the [common attributes reference](./attributes.md#most-common-span-attributes).

## Dash0 semantic convention upgrades

Dash0 automatically normalizes incoming telemetry to a configured semantic convention version at ingestion time. This means:

- **Attribute renames** are applied automatically (e.g., `http.status_code` → `http.response.status_code`)
- **Attribute relocation** moves attributes to their correct level (e.g., `service.name` from span to resource)
- **Metric names** are standardized (e.g., `http.server.duration` → `http.server.request.duration`)
- **Type conversions** are applied where required by the spec

Dash0 offers three upgrade strategies per dataset:

| Strategy | Behavior |
|---|---|
| **Latest** | Continuously migrates to the most recent semantic convention version |
| **Specific version** | Locks to a stable version (e.g., 1.20.0) for consistency |
| **Disabled** | Preserves raw telemetry without transformation |

This means you can upgrade your instrumentation libraries at your own pace — Dash0 handles the normalization. See [Dash0 Semantic Convention Upgrades](https://www.dash0.com/documentation/dash0/semantic-conventions/opentelemetry-semantic-convention-upgrades) for configuration details.

## References

- [Semantic Conventions Repository](https://github.com/open-telemetry/semantic-conventions) — source YAML models, version tags, and changelogs
- [Dash0 Semantic Convention Upgrades](https://www.dash0.com/documentation/dash0/semantic-conventions/opentelemetry-semantic-convention-upgrades) — automatic convention version management
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall