Migrate Telemetry Schemas with the OpenTelemetry Schema Processor

The OpenTelemetry Collector schemaprocessor translates telemetry between versions of a telemetry schema. It reads each signal’s schema_url, fetches the corresponding schema file, and applies schema-defined transformations, such as attribute renames, so signals from instrumentations on different schema versions arrive in Honeycomb with consistent attribute names. The processor works with any schema family that follows the OpenTelemetry telemetry schemas specification. The most common case is migrating between OpenTelemetry semantic convention versions, such as the HTTP semantic conventions stabilization, but the same configuration applies to custom schema families your organization publishes. Rather than writing transform processor OTTL statements by hand, the schema processor reads the schema file and applies the defined renames automatically. This matters for Honeycomb because any feature that references a renamed attribute by name, such as an SLO, Trigger, Calculated Field, Board, saved query, or Refinery rule, stops matching new data until you update that feature.

The schema processor is at alpha stability for traces, metrics, and logs and is distributed in the OpenTelemetry Collector Contrib build. Configuration options and behavior may change between releases. Pin a specific collector version, test in a non-production environment, and read the upstream release notes before upgrading.

When to use the schema processor

Choosing the right tool upfront saves significant rework later. Use the schema processor when:

You are migrating between schema versions where the schema author publishes a telemetry schema file describing the changes. OpenTelemetry semantic conventions are the canonical example; an internal schema family hosted on your own domain also qualifies.
You want to emit both the old and the new attribute names during a transition window so that existing queries, SLOs, Triggers, Boards, and Refinery rules keep working until you cut over.
You operate a fleet of services on mixed instrumentation versions and want a single collector configuration to converge on one consistent set of attribute names.

Use the transform processor instead when:

The rename or rewrite is ad-hoc and not described by a telemetry schema file.
You need conditional logic, value rewrites, or metric unit conversions that the schema files do not express.
You need a stable, generally-available processor and can’t adopt alpha components.

The two processors can coexist in the same pipeline: the schema processor handles schema-driven renames, and the transform processor handles everything else.

How the schema processor works

The processor reads each incoming signal’s schema_url and, if it matches a known schema family, applies the chain of transformations from the signal’s version to the configured target version for that family. By default, a rename replaces the old attribute with the new one. In migration mode (sometimes called copy-mode), the processor instead emits both the old and the new attribute name for renames between a specified from version and the target. This is the safe-rollout pattern: deploy migration mode, update downstream consumers to the new names at your own pace, then remove migration mode to complete the cutover.

Configuration reference

This table covers the most common fields. For the authoritative option list at the version of the collector you run, refer to the upstream schemaprocessor README.

Field	Type	Required	Default	Purpose
`targets`	`[]string`	Yes	—	Schema URLs identifying the target version for each schema family the processor should translate to. One entry per family.
`prefetch`	`[]string`	No	—	Schema URLs to download and cache at collector startup. Useful for warming the cache or ensuring availability in restricted networks.
`migration`	`[]object`	No	—	Migration entries. Each entry has a `target` and a `from` schema URL. While the entry is present, renames between `from` and `target` produce both old and new attribute names.
`storage`	`string`	No	in-memory	ID of a storage extension for persistent schema file caching across collector restarts.
`cache_cooldown`	duration	No	`5m`	Cooldown period after the processor hits the retry limit while fetching a schema.
`cache_retry_limit`	int	No	`5`	Consecutive fetch failures before the processor enters cooldown.

Basic configuration

The minimum configuration sets one or more targets and wires the processor into a pipeline.

processors:
  schema:
    targets:
      - https://opentelemetry.io/schemas/1.27.0

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [schema, batch]
      exporters: [otlp/honeycomb]
    metrics:
      receivers: [otlp]
      processors: [schema, batch]
      exporters: [otlp/honeycomb]
    logs:
      receivers: [otlp]
      processors: [schema, batch]
      exporters: [otlp/honeycomb]

Once deployed, signals arriving with an older schema_url from the same family are translated to the target version’s (in theis case, 1.27.0) attribute names before they leave the collector. To translate multiple schema families at once, including a custom one your organization publishes, list a target URL for each family:

processors:
  schema:
    targets:
      - https://opentelemetry.io/schemas/1.27.0
      - https://schemas.example.com/telemetry/2.0.0

Migration mode for safe rollouts

A hard cutover from old to new attribute names means any Honeycomb feature that references the old names stops matching new incoming data until you update that feature. Migration mode avoids that by coalescing old and new attribute names onto the same span, metric, or log record, so queried referencing either name continue to match while you work through the updates. The recommended workflow is:

Set the new target version. Update targets to the new schema URL.
Add a migration entry. Add a migration entry with the same target and a from pointing at the previous version your fleet is emitting.
Deploy. Telemetry now carries both old and new names for the renames in that version range.
Migrate downstream consumers. Update queries, SLOs, Triggers, Calculated Fields, Boards, and Refinery rule conditions to reference the new names. Verify each in Honeycomb before moving on.
Remove the migration entry and redeploy. The processor stops emitting the old names, and the cutover is complete.

This example migrates from 1.26.0 to 1.27.0:

processors:
  schema:
    prefetch:
      - https://opentelemetry.io/schemas/1.26.0
    targets:
      - https://opentelemetry.io/schemas/1.27.0
    migration:
      - target: https://opentelemetry.io/schemas/1.27.0
        from: https://opentelemetry.io/schemas/1.26.0

After updating downstream consumers, remove the migration block:

processors:
  schema:
    targets:
      - https://opentelemetry.io/schemas/1.27.0

Migration mode duplicates renames only between the from and target you specify. Other transformations defined in the schema files still apply normally.

Verify the migration in Honeycomb

Before removing migration mode, confirm that both attribute name sets are present and that the Honeycomb features depending on the renamed attributes still work. For each feature that depends on a renamed attribute, run these checks:

Query the dataset for the new attribute name and confirm recent events appear.
Query the dataset for the old attribute name and confirm recent events still appear.
Fire a Trigger or evalute an SLO that depends on the renamed attribute against a known event and confirm it evaluates correctly.

Audit the following Honeycomb features that commonly reference attribute names:

SLOs
Triggers
Calculated Fields
Boards and saved queries
Refinery rule conditions and field lists
Other OpenTelemetry Collector configurations downstream of this one

If you use Refinery, confirm rule conditions match. Refinery 2.3 and later support multi-field conditions, which complement migration mode for tail sampling during the transition. After you remove the migration entry, repeat the same checks to confirm the old names are no longer appearing and that nothing still depends on them.

Limitations

Keep these constraints in mind when you plan your pipeline configuration:

The processor applies only transformations defined in telemetry schema files. Ad-hoc or organization-specific renames that aren’t captured in a schema file require the transform processor.
The processor must be able to reach the schema URLs it is configured with. For air-gapped or restricted environments, use prefetch with a storage extension to cache schemas locally.
Signals without a schema_url, or with a schema_url from a family the processor isn’t configured to handle, pass through untouched.
Alpha stability means option names and defaults may change between collector releases. Validate after every upgrade.

These resources cover the tools and migration paths that work alongside the schema processor:

Handle Sensitive Information with the OpenTelemetry Collector: Covers the transform processor and OTTL, the imperative alternative for arbitrary attribute rewrites.
Migrate to Stabilized OpenTelemetry HTTP Semantic Conventions: The HTTP semantic conventions migration guide with worked OTTL coalescing examples.
Customize Telemetry Schema: A distinct, Honeycomb-side feature that resolves attributes at query time using overlay schemas. It does not transform data on ingest and is not a substitute for the schema processor.
Upstream schemaprocessor README
OpenTelemetry Telemetry Schemas specification

Documentation Index

​When to use the schema processor

​How the schema processor works

​Configuration reference

​Basic configuration

​Migration mode for safe rollouts

​Verify the migration in Honeycomb

​Limitations

​Related Topics

When to use the schema processor

How the schema processor works

Configuration reference

Basic configuration

Migration mode for safe rollouts

Verify the migration in Honeycomb

Limitations

Related Topics