Last updated: March 27, 2026
Semantic Convention Upgrades
Overview
OpenTelemetry semantic conventions evolve over time to improve clarity, consistency, and completeness in telemetry data. These changes can include renaming attributes, moving attributes across levels, or updating metric names. Dash0 provides automatic schema migration capabilities that transform your telemetry data during ingestion to align with the OpenTelemetry semantic conventions version of your choice, for consistency across your observability data without requiring changes to your instrumentation code.
Understanding Schema Migrations
Schema migrations in Dash0 automatically handle the evolution of OpenTelemetry semantic conventions. Common migrations include:
- Attribute Renaming: Updating attribute names to align with the latest conventions (e.g.,
http.status_codetohttp.response.status_code). - Attribute Relocation: Moving attributes to their proper level (e.g., moving
service.namefrom span attributes to resource attributes). - Metric Name Standardization: Updating metric names to follow the current conventions.
- Type Conversions: Converting attribute values to comply with specification requirements.
Schema migrations operate at ingestion time without requiring changes to your instrumentation code, making it easy to maintain consistency even with diverse telemetry sources.
Configuration Options
Schema migrations in Dash0 are configured at the dataset level, allowing you to apply different migration strategies to different environments. The available options include:
- Latest: Always apply migrations to the most current version of OpenTelemetry semantic conventions.
- Specific Version: Select a stable semantic convention version (e.g., 1.20.0, 1.19.0) to ensure consistency even as new versions are released.
- Disabled: Do not apply any schema migrations (raw telemetry is preserved).
How Schema Migrations Work
When telemetry data is received, Dash0 examines the data and applies the appropriate transformations based on your configuration. This happens transparently before the data is indexed and stored, so that queries, dashboards, and alerts operate on consistent data.
Here's an example of how a schema migration works for an HTTP access log with the legacy http.status_code attribute and a wrongly positioned service.name attribute. The example uses OpenTelemetry's OTLP data format.
Before migration:
12345678910111213141516171819202122232425resourceLogs:- resource:attributes:- key: k8s.pod.namevalue:stringValue: opentelemetry-demo-productcatalogservice-54596f6bd8-rbd57- key: k8s.pod.uidvalue:stringValue: 96fbbe11-9bdf-48c6-a0c8-c5b972df540cscopeLogs:- logRecords:- attributes:- key: service.namevalue:stringValue: productcatalogservice- key: http.status_codevalue:intValue: "404"body:stringValue: "GET /products/81jkfa89obkda"severityNumber: 9severityText: "INFO"spanId: L/fKDoHFkzg=traceId: NatRZh4+DXVfO+rpANjCgw==timeUnixNano: "1747637717357189408"
After migration:
12345678910111213141516171819202122232425resourceLogs:- resource:attributes:- key: k8s.pod.namevalue:stringValue: opentelemetry-demo-productcatalogservice-54596f6bd8-rbd57- key: k8s.pod.uidvalue:stringValue: 96fbbe11-9bdf-48c6-a0c8-c5b972df540c- key: service.namevalue:stringValue: productcatalogservicescopeLogs:- logRecords:- attributes:- key: http.response.status_codevalue:intValue: "404"body:stringValue: "GET /products/81jkfa89obkda"severityNumber: 9severityText: "INFO"spanId: L/fKDoHFkzg=traceId: NatRZh4+DXVfO+rpANjCgw==timeUnixNano: "1747637717357189408"
In this example, two migrations are applied:
- The
http.status_codeattribute is renamed tohttp.response.status_code. - The
service.nameattribute is moved from log record attributes to resource attributes.
The data now has a chance to be consistent across services.
Note: Dash0 typically further enriches log records like these through the application of Log AI.