OpenTelemetry Java agent 2.32.0 has been released as the release candidate for the upcoming 3.0 version, which is targeted for October 2026. The update gives engineering teams an opportunity to test several important changes involving semantic conventions, telemetry capture, instrumentation defaults and exporter compatibility before they become standard behaviour. For organisations that rely heavily on OpenTelemetry for observability, the preview period is particularly useful because some of the changes affect not only attribute names but also span relationships, metric units and how telemetry is grouped.
The release moves database and code semantic conventions towards their stable forms while messaging adopts newer conventions that are still considered experimental. Some behaviour may still change before OpenTelemetry Java agent 3.0 is finalised. Grafana Labs Staff Software Engineer Jay DeLuca has outlined a migration approach that focuses on comparing old and new telemetry side by side before switching completely to the new defaults.
Start By Capturing A Baseline
The recommended migration process begins with capturing baseline telemetry before enabling the full 3.0 preview behaviour. Teams can keep OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=false while opting into dual telemetry for specific domains. Database and code conventions can be tested with OTEL_SEMCONV_STABILITY_OPT_IN=database/dup,code/dup, while messaging can use OTEL_SEMCONV_STABILITY_PREVIEW=messaging/dup.
The /dup configuration allows supported instrumentation to emit both legacy and newer attributes at the same time. Where dual metrics are available, teams can compare those as well. This gives operators a safer way to examine how existing dashboards, alerts and queries will behave before committing to the new conventions.
Database Changes Go Beyond Simple Attribute Renaming
One of the important lessons from the migration guidance is that teams should compare actual values and units rather than assuming the update is simply replacing one attribute name with another. In the PostgreSQL JDBC example, a connection to an orders database using the public schema previously emits db.name as orders. Under the stable convention, db.namespace becomes orders|public, meaning the new field contains additional context rather than being a direct one-to-one rename.
There are other naming changes as well. A db.system value of mssql becomes db.system.name with the value microsoft.sql_server. For code telemetry, the previous code.namespace and code.function fields are consolidated under code.function.name, so queries and dashboards that depend on the older structure will need to be reviewed.
Metric units are another area requiring attention. Database connection-pool duration metrics are moving from milliseconds to seconds. Any alert thresholds, recording rules or visualisations that previously assumed milliseconds must therefore be converted rather than simply pointed at the new metric.
Dual Emission Does Not Mean Everything Is Duplicated
Even when database/dup is enabled, some telemetry cannot exist in both old and new forms simultaneously. Connection-pool metrics adopt their new names and units even under dual emission. Similarly, spans retain only one span name and one span kind, so the newer convention is used for those properties even while attributes may be duplicated.
Once teams are ready to test the combined OpenTelemetry 3.0 behaviour, setting OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=true activates the newer conventions and defaults together. This also disables dual emission for those domains. To isolate semantic convention changes from broader default changes, DeLuca recommends leaving the umbrella preview flag disabled and removing /dup from the individual domain settings instead.
Database Endpoint Grouping May Change Service Graphs
The update also changes how database endpoints may be represented. For supported clients, server.address describes the configured destination and may represent a list of cluster endpoints. Meanwhile, network.peer.address can identify the actual endpoint contacted by the application when that information is available.
This distinction matters because service graphs and backend grouping can change even when there is no obvious attribute rename. If observability systems currently group database activity according to host or endpoint information, teams should confirm that those relationships still appear as expected. Otherwise, the migration could result in services or database connections being grouped differently without any underlying application change.
Kafka Messaging Telemetry Changes Significantly
Messaging telemetry is moving from semantic conventions version 1.24 to version 1.43, bringing a number of visible changes for Kafka users. Span names such as orders publish, orders receive and orders process are replaced by send orders, poll orders and process orders. The older messaging.operation attribute is also split into separate operation name and operation type fields.
For example, a Kafka polling operation can now have an operation name of poll and an operation type of receive. This provides a more structured representation of messaging activity, but it also means existing trace queries and dashboards based on the old operation attribute will need updating. Teams should pay particular attention to any tooling that assumes specific span names.
Kafka Parent And Link Relationships Are Also Different
The relationship between producer and consumer spans is changing as well. For single-message processing where producer context is propagated, an active application span on the consumer side becomes the parent of the process span under the preview behaviour. The process span then links to the producer span rather than inheriting it as its direct parent.
When receive spans are enabled and no active consumer-side application span exists, the process span can instead become a child of the send span within the same trace. The poll span represents a separate client operation, changes its span kind from CONSUMER to CLIENT, and links back to the send span. Batch processing behaves differently again because a batch can link to multiple messages rather than following the single-message relationship.
Receive spans remain opt-in. In Kafka instrumentation 2.32.0, enabling receive telemetry also enables poll-duration metrics. Unlike the database changes, Kafka did not previously emit the legacy messaging instruments referenced here, so using messaging/dup does not provide two complete metric sets for direct comparison.
Structured Logging Capture Becomes More Consistent
The 3.0 preview also changes how structured logging data is captured. Existing SLF4J structured key-value fields can be exported automatically when the umbrella preview is enabled, without requiring a separate capture switch. MDC remains independently configured and continues to be opt-in.
The configuration model is also being simplified. Common .included and .excluded selectors replace several source-specific structured-field settings, and the preview mode ignores the older options. Administrators should take care when migrating configurations because glob patterns behave differently from literal capture lists. Copying a value such as * into the new selector could unintentionally collect far more data than the old configuration did.
User Identity Telemetry Gets New Attributes
User identity capture remains optional, but the relevant attributes are changing. enduser.id becomes user.name, while enduser.role, previously represented as a comma-separated value, becomes the user.roles string array. The existing enduser.scope attribute does not receive a direct replacement.
Applications that explicitly capture identity information should therefore review both their instrumentation and the downstream systems consuming those fields. Queries, processors and dashboards expecting the older enduser.* attributes will otherwise stop matching once the new conventions are enabled. Since user-related telemetry can also have privacy implications, this is a good point for organisations to reassess what they actually need to collect.
Some Instrumentations Will Be Disabled By Default
Several instrumentations are changing their default behaviour in preparation for OpenTelemetry Java agent 3.0. Hibernate, Hystrix and Twilio instrumentation will default to disabled and must be explicitly re-enabled by users who still rely on them. Teams upgrading without checking these defaults could therefore notice missing telemetry even though their applications continue operating normally.
Extension developers also need to prepare for invokedynamic instrumentation becoming the default approach. This changes how instrumentation and helper classes are loaded, potentially affecting custom extensions that depend on previous agent internals. Anyone maintaining OpenTelemetry Java extensions should test against 2.32.0 before the final 3.0 release rather than waiting until the upgrade becomes mandatory.
Zipkin Exporter Support Is Removed In Preview Mode
Another important compatibility change involves the Zipkin exporter. Support for it is removed when the 3.0 preview behaviour is enabled. Existing configurations that continue to reference the Zipkin exporter may cause agent or SDK initialisation to fail.
Organisations still exporting telemetry directly through Zipkin should therefore migrate to OTLP before moving fully to the 3.0 defaults. This aligns with the broader OpenTelemetry ecosystem, where OTLP has increasingly become the standard transport for sending traces, metrics and logs to observability backends.
Why Teams Should Test Before Version 3.0
OpenTelemetry Java agent 2.32.0 is valuable because it gives teams time to uncover migration issues before the new defaults become unavoidable. Changes involving metric units, span names, parent relationships and endpoint grouping can quietly break dashboards or alerting even when applications themselves remain unaffected. Running old and new telemetry side by side wherever possible provides much better visibility into those differences.
The most important step is to avoid treating the migration as a simple schema rename. Some telemetry changes meaning, some changes units, and some changes how traces are structured. Observability systems built on top of that data therefore need validation just as carefully as the instrumentation itself.
Final Thoughts
OpenTelemetry Java agent 2.32.0 is effectively the dress rehearsal for version 3.0. It introduces the upcoming stable database and code conventions, newer Kafka messaging semantics, revised structured-data capture, different default instrumentation behaviour and a move away from Zipkin towards OTLP. For teams operating large observability environments, the update provides a useful window to test all of these changes before the final October 2026 release.
The safest migration strategy is to establish a baseline, enable dual telemetry where available and compare not only names but also values, units, span relationships and service grouping. Teams that do this work now should have a much smoother transition when OpenTelemetry Java agent 3.0 makes these behaviours the default.
Comments 0