OpenTelemetry Today and Tomorrow

A team adopted OpenTelemetry in 2024. The team pinned the Python SDK at 1.27.0 and the Java SDK at 1.42.0. The Collector was pinned at 0.110.0. By 2026 the team reads the release notes and discovers that several signal components the team depends on are still labelled experimental. A new profiles signal graduated from experimental to beta in 2025. The semantic conventions moved from 1.x to 2.x and several attribute names changed. The team faces the question every OTel adopter faces: which version pins are still safe, which need to move, and what is the migration path?

The OpenTelemetry project publishes a stability matrix that names the maturity of every component. The matrix is the single source of truth for “is this safe to depend on”. The lesson that follows reads the matrix, names the signal components that have graduated and the ones still in flux, and walks the migration discipline that keeps the fleet current without breaking production.

What it is

The OpenTelemetry project publishes a stability matrix at opentelemetry.io/docs/specs and opentelemetry.io/v1.X (where X is the spec version). The matrix has four tiers.

• Stable — the API, the data model, the wire format, and the SDK behaviour are all backwards-compatible. Breaking changes require a major version bump of the SDK and a new protobuf schema version. Metrics, logs, and traces have been Stable since approximately 2021-2023 depending on the language SDK.
• Beta — the data model and the wire format are stable but minor behaviour may change between minor SDK versions. Profile data is at Beta as of 2025.
• Experimental — the data model and the wire format may change without notice. The SDK may emit a warning. The Collector may require a feature gate. Some signal components and many semantic-convention attributes are at Experimental at any given moment.
• Deprecated — the component is still functional but is slated for removal. The migration path is documented in the spec.

The matrix is per-component, not per-signal. A signal type (metrics, logs, traces, profiles) can be Stable while a specific component within that signal is Experimental. For example, traces are Stable, but the otel.profiling span attribute is Experimental.

Spec versions, SDK versions, schema versions

Three version numbers move on different cadences. The operator who conflates them misreads the stability matrix.

• Spec version — the OpenTelemetry specification version. The spec is a document set; the version is on the document. Spec versions evolve slowly; a major bump is a deliberate decision by the specification committee.
• SDK version — the per-language SDK version. The SDK follows SemVer; major bumps are backwards-incompatible API changes; minor bumps add features; patch bumps fix bugs. The SDK release cadence is monthly.
• Protobuf schema version — the OTLP wire format version. The schema is a set of .proto files; the version is on the package declaration. A 1.x schema is a wire contract; a 0.x schema is a draft.

A change to the data model happens in the spec first, then in the proto schema, then in the SDK. The three changes are not synchronised; an SDK release may carry a newer spec without a newer protobuf schema.

The new signals

The OpenTelemetry project has been adding signals since 2024.

• Profiles — continuous runtime profiling. Beta in 2025. Go and Java have production-grade exporters; the other languages are at various stages.
• Events — discrete user-defined events with structured attributes. Experimental. Designed to fill the gap between logs (high-cardinality text) and metrics (low-cardinality counters) for “things that happened but are not a log line”.
• Entities — first-class entities in the resource model (for example, a Kubernetes node, a database, a queue). Experimental. Designed to make the Resource model richer than the flat set of attributes it is today.

The new signals share the same wire protocol (OTLP) and the same data-model philosophy. Adopting them is a configuration change, not a wire change.

Why a sysadmin cares

Three failure shapes appear when the stability matrix is ignored.

1. The experimental receiver that disappeared. A team adopts the k8scluster receiver at version 0.99. The receiver was Experimental. The next minor Collector release renames it or removes it. Symptom: the Collector refuses to start with component "k8scluster" not found. The fix is to read the stability matrix before adopting; the discipline is to prefer Stable components for production pipelines.
2. The semconv drift that broke every dashboard. A team pins semconv 1.24.0. The 2.x line is published. The team’s dashboards group by http.method. The new SDK emits http.request.method. Symptom: dashboards return half the expected traffic. The fix is to align the fleet on one semconv version or to migrate the dashboards.
3. The breaking change in a minor SDK version. A team pins the Java SDK at 1.42.0. The 1.43.0 release changes the default sampler from parentbased_always_on to parentbased_traceidratio at 1.0. Symptom: the trace rate drops by 99 percent. The fix is to read the release notes before bumping; the discipline is to pin minor versions explicitly and to test on a canary before rolling out.

The matrix is the answer. The discipline is to read it quarterly.

How it works

The mental model. The OpenTelemetry project maintains three release trains that move at different cadences.

   Specification       SDK (per language)     Protobuf schema
   (slow, deliberate)  (monthly)              (per release)
        |                    |                       |
        +---- driven by -----+------- defines ------+
                             |
                             v
                     Wire format + SDK
                             |
                             v
                     Collector + backends

A change to the spec drives a change to the proto schema (a breaking change to the wire format) and a change to the SDK (an API or behaviour change). The SDKs release independently per language, but the proto schema is shared.

The release cadence

The OpenTelemetry project publishes release notes for every SDK and for the Collector. The cadence is:

• Specification — irregular; a major version is a multi- quarter decision.
• SDKs (per language) — monthly; minor releases add features; patch releases fix bugs.
• Collector — monthly; the contrib and core distributions release on the same cadence.
• Protobuf schema — per release; the version is on the package.

The release notes are the operator’s source of truth. The matrix is the summary; the notes are the detail.

Migration paths

The OTel project publishes migration notes for every breaking change. The migration surface is:

• API rename — the SDK provides a deprecated alias for one minor version; the alias is removed in the next major.
• Default behaviour change — the SDK flips a default; the operator can pin the previous default explicitly.
• Data model change — the SDK adds a new attribute; the old attribute is deprecated; the migration is to switch queries to the new attribute over one release cycle.
• Component rename — the Collector renames a receiver, processor, or exporter; the old name is kept as an alias for one release cycle; the alias is removed in the next major.

The migration paths are documented in the spec, in the release notes, and in the SDK’s CHANGELOG. The discipline is to read all three before bumping a pinned version.

How to configure it

The configuration surface for “what is enabled today” is the Collector pipelines block and the SDK environment variables. The configuration surface for “what is graduating” is the release notes and the feature gate environment variables.

Collector: enable a pipeline for an experimental signal.

# /etc/otelcol/config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 80
    spike_limit_percentage: 25
  batch:
    timeout: 5s
    send_batch_size: 8192

exporters:
  otlp/profiles:
    # Profile backends are still emerging; the exporter
    # placeholder is enabled but the destination is empty.
    endpoint: profiles.internal.example.com:4317
    tls:
      insecure: false
      ca_file: /etc/otelcol/ca.pem

service:
  telemetry:
    metrics:
      address: localhost:8888
    logs:
      level: info
  pipelines:
    traces:
      receivers:  [otlp]
      processors: [memory_limiter, batch]
      exporters:  [otlp/tempo]
    metrics:
      receivers:  [otlp]
      processors: [memory_limiter, batch]
      exporters:  [otlp/mimir]
    logs:
      receivers:  [otlp]
      processors: [memory_limiter, batch]
      exporters:  [otlp/loki]
    profiles:
      receivers:  [otlp]
      processors: [memory_limiter, batch]
      exporters:  [otlp/profiles]

The profiles pipeline accepts the OTLP profile records. The pipeline must exist even when the exporter destination is empty; the SDK needs a drain or it will retry.

SDK: opt in to a graduating semconv version.

# Java SDK: pin the semconv version explicitly.
OTEL_SEMCONVN_STABLE_OPT_IN=http

# Python SDK: pin the semconv version.
from opentelemetry.semconv.trace import SpanAttributes
# Or for the 2.x conventions:
from opentelemetry.semconv._incubating.attributes.http_attributes import (
    HttpAttributes,
)

The opt-in switches the SDK to emit the new attribute names. The migration is per-application; the fleet must align.

How to validate it

Validate that the version pins are current, the experimental components are intentional, and the semconv version is aligned.

# READ-ONLY: confirm the Collector version.
otelcol --version

otelcol-contrib version 0.110.0

# READ-ONLY: list the components in the running binary.
otelcol components | head -20

receivers:
  - otlp
  - filelog
  - hostmetrics
  - k8scluster
processors:
  - batch
  - memory_limiter
  - tail_sampling
  - transform
exporters:
  - otlp
  - otlphttp
  - loki

# READ-ONLY: confirm the experimental receiver is loaded.
otelcol components | grep k8scluster

receivers:
  - k8scluster (experimental)

The (experimental) annotation is the matrix speaking. A production pipeline that depends on an experimental component should have an alternative path for the day the component graduates or is removed.

# READ-ONLY: confirm the SDK version in the application.
# Java
unzip -p checkout.jar META-INF/MANIFEST.MF | grep Implementation-Version

Implementation-Version: 1.42.0

# READ-ONLY: confirm the SDK version in Python.
pip show opentelemetry-sdk | grep Version

Version: 1.27.0

The SDK version pin is in the application’s manifest. The release notes for that pin are the operator’s next read.

How it can fail

Five failure modes that arise from ignoring the stability matrix.

1. The experimental receiver that was renamed. A team adopts k8scluster at Collector 0.95.0. The next minor release renames it to k8sobjects. Symptom: the Collector refuses to start with component "k8scluster" not found. The fix is to migrate the pipeline to the new name; the discipline is to check the Collector release notes before bumping.
2. The semconv drift that broke every dashboard. The team pins semconv 1.24.0; the SDK emits http.method. The 2.x line publishes http.request.method. Symptom: dashboards return half the expected traffic. The fix is to align the semconv version across the fleet.
3. The breaking change in a minor SDK version. The team pins Java SDK 1.42.0. The 1.43.0 release changes the default sampler. Symptom: the trace rate drops by 99 percent. The fix is to read the release notes before bumping.
4. The profile signal without a backend. The team enables the profiles pipeline but no profiles backend exists. Symptom: the agent’s queue fills; the SDK retries; the application thread pool stalls. The fix is to remove the unused pipeline until a backend exists or to disable profile export at the SDK.
5. The feature gate that was removed. The team enables the profiles feature gate at Collector 0.95.0. The 0.110.0 release enables profiles by default and removes the gate. Symptom: the Collector fails to start with unknown feature gate "profiles". The fix is to remove the gate flag when upgrading.

How to troubleshoot it

When the upgrade fails, the diagnostic order is from the matrix forward.

1. What is the stability tier? The OTel status page or the spec site names every component and its tier. Cross- reference against the production pipeline; any Experimental component should have an alternative path.
2. What changed in this release? The release notes for the pinned version name every breaking change. Read before bumping.
3. Is the semconv version aligned? The SDK and the Collector must agree on the semconv version. A mismatch produces attribute names that the destination backend does not index.
4. Is the feature gate still valid? The Collector CLI rejects unknown feature gates. The fix is to remove the gate when the component graduates.
5. Is the experimental component still in the binary? otelcol components lists every component in the running binary. Cross-reference against the pipeline config.

Security implications

The migration paths cross security boundaries that change with the version.

• TLS bundle rotation. A semconv bump may rename the server.address attribute or add a new client.address attribute. A redaction policy that hard-codes attribute names will silently leak the renamed attribute. The fix is to use the semconv constants in the redaction config, not the string literals.
• Authorisation headers. A new HTTP semconv attribute may carry an authorisation header value. The SDK redactor must be updated to drop the new attribute. The discipline is to read the security note in the release notes for every semconv bump.
• Collector TLS configuration. A Collector upgrade may require a new TLS configuration knob. The migration path is in the release notes; the discipline is to read them.

Performance implications

The migration paths affect performance in three places.

• Cardinality. A new attribute may have unbounded values (for example, a new http.route that includes the user ID). The cardinality budget for the destination backend may be exceeded. The fix is to cap the cardinality at the SDK or at the Collector before the upgrade.
• Batch size. A new signal type (for example, profiles) may add a second batched pipeline. The Collector’s batch processor settings may need to be retuned to accommodate the new volume.
• Wire payload. A new attribute set typically increases the wire payload by 5-15 percent. The compression and batching settings should be reviewed.

Production guidance

• Pin the SDK and Collector versions explicitly. Patches and minors; majors only after a migration plan.
• Read the release notes for every pinned version. The release notes name every breaking change; the matrix names the stability tier.
• Treat the stability matrix as a quarterly review. The Experimental components in production today will graduate or be removed in the next year.
• Migrate one semconv version at a time. The migration from 1.x to 2.x is a multi-step process; the disciplined path is one minor bump per release cycle.
• Have an alternative path for every experimental component. A rename or removal should not become an incident.
• Smoke test every upgrade on a canary. The SDK or Collector bump should ship to a canary first; the smoke test should exercise every signal type and every experimental component.

Verification

You should now be able to answer:

• What are the four tiers in the OTel stability matrix?
• What is the difference between the spec version, the SDK version, and the protobuf schema version?
• What is the migration path when an experimental receiver is renamed?
• Which signals are Stable, which are Beta, and which are Experimental as of 2026?
• What is the discipline for adopting a graduating semconv version in a multi-language fleet?

Quiz