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, ensuring 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:

1. Attribute Renaming: Updating attribute names to align with the latest conventions (e.g., http.status_codeCopy to http.response.status_codeCopy).
2. Attribute Relocation: Moving attributes to their proper level (e.g., moving service.nameCopy from span attributes to resource attributes).
3. Metric Name Standardization: Ensuring metric names follow the current conventions.
4. 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).

Dataset settings showing the semantic convention upgrade configuration options

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, ensuring 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_codeCopy attribute and a wrongly positioned service.nameCopy attribute. The example is using OpenTelemetry's OTLP data format (you can also see this in Dash0's source tab).

12345678910111213141516171819202122232425
resourceLogs:
  - resource:
      attributes:
        - key: k8s.pod.name
          value:
            stringValue: opentelemetry-demo-productcatalogservice-54596f6bd8-rbd57
        - key: k8s.pod.uid
          value:
            stringValue: 96fbbe11-9bdf-48c6-a0c8-c5b972df540c
    scopeLogs:
      - logRecords:
          - attributes:
              - key: service.name
                value:
                  stringValue: productcatalogservice
              - key: http.status_code
                value:
                  intValue: "404"
            body:
              stringValue: "GET /products/81jkfa89obkda"
            severityNumber: 9
            severityText: "INFO"
            spanId: L/fKDoHFkzg=
            traceId: NatRZh4+DXVfO+rpANjCgw==
            timeUnixNano: "1747637717357189408"

The code block above shows a sample HTTP access log with two attributes that can cause inconsistent data, as mentioned above. Let's see what this looks like once the log has passed through Dash0's schema migrator:

12345678910111213141516171819202122232425
resourceLogs:
  - resource:
      attributes:
        - key: k8s.pod.name
          value:
            stringValue: opentelemetry-demo-productcatalogservice-54596f6bd8-rbd57
        - key: k8s.pod.uid
          value:
            stringValue: 96fbbe11-9bdf-48c6-a0c8-c5b972df540c
        - key: service.name
          value:
            stringValue: productcatalogservice
    scopeLogs:
      - logRecords:
          - attributes:
              - key: http.response.status_code
                value:
                  intValue: "404"
            body:
              stringValue: "GET /products/81jkfa89obkda"
            severityNumber: 9
            severityText: "INFO"
            spanId: L/fKDoHFkzg=
            traceId: NatRZh4+DXVfO+rpANjCgw==
            timeUnixNano: "1747637717357189408"

In this example, two migrations are applied:

1. The http.status_codeCopy attribute is renamed to http.response.status_codeCopy
2. The service.versionCopy attribute is moved from span attributes to resource attributes.

The data now has a chance to be consistent across services. Note that Dash0 typically further enriches log records like these through the application of Log AI.