Skip to main content
This page summarizes the essential rules and best practices for OpenTelemetry schema transforms. Use it as a quick reference when authoring schema files for the collector’s schema processor. Key takeaways:
  • Patch increments imply no behavioral changes for consumers.
  • Minor increments add optional, backward-compatible items.
  • The all section may only contain rename_attributes and runs before signal-specific rules.
  • Transform order matters: apply global (all) rules before signal-specific transforms.
  • When migrating between schema versions, step through intermediate versions sequentially (X → X+1 → … → Y).
  • Use rename_metrics to change a metric’s name and rename_attributes to change labels/attributes.
  • Resource-level renames use rename_attributes.
  • Always set schema_url to the highest schema version declared; it travels with telemetry.
  • In metrics.rename_attributes, omitting apply_to_metrics makes the renaming apply to all metrics.
  • Span selectors and event selectors can scope renames to specific spans or span events.
  • The collector’s schema processor upgrades/downgrades telemetry by applying rename-based transforms in version order.
  • Keep transforms minimal and rename-focused to limit complexity and reduce the chance of unintended semantic changes.
The image is a slide titled "Knowledge Check #1 – File Format and Order," showing five concepts related to software versioning processes, including patch increment, minor increment, all section, transform orders, and version stepping.
Practical notes and rules of thumb
  • Always put all (global) rename_attributes rules first so broad attribute renames are applied before signal-specific renames.
  • Use rename_metrics for the metric name itself and rename_attributes for metric labels.
  • Use apply_to_metrics (when available) to scope an attribute rename to selected metric names; if omitted, the rename applies to all metrics.
  • For spans and span events, use selectors such as apply_to_spans or apply_to_events to limit renames to specific names or patterns.
The image outlines four steps about URLs and schema evolution, focusing on schema URLs, processors, versioning, and transformation types, using icons and colored backgrounds to distinguish each step.
Quick reference table — transform types and example usage
Transform typePurposeExample
rename_metricsChange the metric’s canonical nameyaml<br> - rename_metrics:<br> old.metric.name: new.metric.name<br>
rename_attributes (metrics)Rename metric labels; can be scoped with apply_to_metricsyaml<br> - rename_attributes:<br> attribute_map:<br> old_label: new_label<br> apply_to_metrics: ["new.metric.name"]<br>
rename_attributes (resources)Rename resource attributesyaml<br> - rename_attributes:<br> attribute_map:<br> old_resource_attr: new_resource_attr<br>
Conditional selectorsScope renames to spans or eventsyaml<br> - rename_attributes:<br> attribute_map:<br> old_label: new_label<br> apply_to_spans: ["service.span.name"]<br> apply_to_events: ["span.event.name"]<br>
Example schema snippet (concise)
Best practice: Always set schema_url to the highest schema version you list in the configuration. The schema URL travels with telemetry and the collector uses it to decide which transforms to apply when upgrading or downgrading. For further details, see the OpenTelemetry schema docs: https://opentelemetry.io/docs/.
Final recap — rules to remember
  • Schema versioning follows semantic versioning: patch = no change, minor = backward-compatible additions, major = breaking changes.
  • Schema files have organized sections: all, resources, spans, span_events, metrics, and logs. Use each section for focused transforms.
  • The collector’s schema processor applies transforms sequentially, version-by-version (X → X+1 → … → target).
  • Favor rename-only transforms and minimal change sets to avoid accidental semantic shifts.
Validate your YAML and ensure keys and schema_url values are spelled correctly (for example, opentelemetry.io). YAML syntax errors or incorrect keys can prevent the collector from loading schema transforms.

Watch Video