Java with OpenTelemetry 2.32.0 previews what will break in 3.0

Java received version 2.32.0 of the OpenTelemetry agent as a release candidate for 3.0, expected in October 2026. The goal is clear. The version allows testing convention, capture, and instrumentation changes before they become the default.

Database and code semantic conventions become stable defaults. In addition, messaging, in turn, adopts newer conventions that remain experimental.

Therefore, some behaviors may still change before the final release.

Jay DeLuca, a senior software engineer at Grafana Labs, described a migration process for testing and deployment.

Capture current telemetry before enabling the Java preview

The initial recommendation seems obvious, yet many people skip it. It's worth recording the baseline before any change.

The approach involves keeping the guard flag off. Then, simply enable dual emission for database, code, and messaging.

This way, old and new attributes are emitted together. However, the same applies to metrics, where dual emission works.

There's an important caveat in this comparison. Checking only the attribute name lets errors slip through, since values and units also change.

Values change, not just names

The example with JDBC and PostgreSQL illustrates this well. A connection to the orders database in the public schema generates the legacy db.name as orders.

The new db.namespace, however, comes out as orders|public.

Other changes follow the same logic. The value mssql in db.system becomes microsoft.sql_server in db.system.name.

On the code side, two attributes merge. code.namespace and code.function become code.function.name.

The pool duration metric deserves special attention. The unit changes from milliseconds to seconds, which requires converting all alert thresholds.

An additional detail is worth noting. Pool metrics adopt new names and units even with dual emission enabled.

Java and Kafka: trace relationships change shape

Messaging jumps from the v1.24 conventions to v1.43. Span names change significantly.

Before, they were orders publish, orders receive, and orders process. Now they come out as send orders, poll orders, and process orders.

The old messaging.operation attribute splits into name and type. A Kafka poll, for example, has name poll and type receive.

The parent-child relationship depends on execution at the consumer. With single-message processing and propagated context, an active application span becomes the parent of the process span in the preview.

In that case, the process span only links to the producer. But with active receive spans and no active span at the consumer, it becomes a child of the send span in the same trace.

The poll span also changes nature. It goes from CONSUMER to CLIENT and links to the send span.

Batch processing follows a different model. It can link to multiple messages.

Receive spans remain optional. Enabling this telemetry, however, also turns on poll duration metrics.

Endpoint grouping and user capture

This part affects existing dashboards. For supported clients, server.address describes the configured destination, possibly a list of cluster endpoints.

network.peer.address, in turn, identifies the endpoint actually contacted. Consequently, grouping in the service graph changes without any attribute renaming.

User identity capture remains optional, but with new configuration. enduser.id becomes user.name.

enduser.role stops being a comma-separated string and becomes an array in user.roles. enduser.scope, meanwhile, remains without a replacement.

Java with disabled instrumentations and Zipkin out

Three instrumentations come disabled by default. They are Hibernate, Hystrix, and Twilio, which require explicit re-enabling.

Those who maintain extensions face another adjustment. invokedynamic instrumentation becomes the default, which changes instrumentation and helper class loading.

The most urgent alert involves the exporter. Zipkin support was removed in preview mode.

Configurations that still use this exporter may fail during agent startup. Switching to OTLP, therefore, becomes a requirement.

The practical migration roadmap

First, enable dual emission and collect the baseline. Then, compare values and units, not just names.

Next, isolate the changes. Leave the guard flag off and remove the duplication suffix to separate convention from default.

In addition, review alerts and dashboards. Units in seconds and endpoint grouping change results without warning.

Finally, test Kafka carefully. The change in parent-child relationships between spans significantly alters distributed trace readings.

Follow our profile on Instagram!