OpenTelemetry helps Java applications collect traces, metrics, and logs without requiring developers to add instrumentation code to every application method. The Java agent can automatically instrument frameworks, database clients, HTTP libraries, messaging systems, and other supported components.
However, instrumentation defaults do not remain unchanged forever. As OpenTelemetry semantic conventions mature, attribute names, metric units, span relationships, and capture behavior evolve. These changes can affect dashboards and alerting systems even when the application itself has not changed.
The OpenTelemetry Java agent 3.0 introduces an important set of default changes. The 2.32.0 release provides an opportunity to preview these changes before they become the standard behavior. Database and code semantic conventions move to stable versions, messaging adopts newer conventions that remain experimental, and several instrumentation and capture defaults change.
For teams operating Java services in production, the challenge is not simply upgrading the agent. It is making sure that the observability platform continues to interpret the new telemetry correctly.
Understand What Is Changing
The Java agent 3.0 changes three important areas:
Semantic conventions used in exported telemetry.
Instrumentation and data-capture defaults.
Agent configuration and initialization behavior.
These changes can affect the data received by an OpenTelemetry Collector, a tracing backend, a metrics platform, or a log analytics system.
Consider a Java service that currently exports database spans containing attributes such as db.system and db.statement. Its dashboards may use those attributes to identify database operations, group queries, or calculate latency.
After adopting the newer conventions, some of those attributes use different names and structures. A dashboard that still queries the previous attributes may stop displaying the expected information.
The application can continue working normally while its observability dashboards become incomplete. This is why the agent upgrade should be treated as a telemetry migration.
Preview the New Defaults Before Upgrading
The OpenTelemetry Java agent 2.32.0 provides a preview of the changes planned for version 3.0.
The preview can be enabled using an environment variable:
OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=true
It can also be configured through system properties:
java \
-Dotel.instrumentation.common.v3-preview=true \
-javaagent:opentelemetry-javaagent.jar \
-jar application.jar
The exact configuration should be checked against the agent version being tested. For a production evaluation, use the official configuration documentation rather than assuming that every preview option is supported by every agent release.
The preview changes several defaults together. It is therefore useful to test individual semantic convention changes first, then enable the combined preview.
This separation makes it easier to identify whether a problem comes from an attribute change, a metric change, or a different instrumentation default.
Migrate Database Semantic Conventions
Database instrumentation is one of the areas with significant changes.
The newer conventions use more precise attribute names and distinguish database identity from the database query itself.
For example, the following attributes illustrate some of the changes:
Previous attribute | New attribute | Purpose |
|---|
db.system | db.system.name | Identifies the database management system |
db.name | db.namespace | Identifies the database namespace |
db.statement | db.query.text | Contains the database query text |
The actual values can also change. For example, a Microsoft SQL Server database may previously have been represented using the value mssql, while the newer convention uses microsoft.sql_server.
The meaning of an attribute should be checked before updating a query. A simple rename is not always sufficient.
Database namespace information can also include schema details. In a PostgreSQL example, a database named orders using the public schema may produce a namespace value such as orders|public.
Database connection-pool metrics also change. For example, db.client.connections.max becomes db.client.connection.limit. Duration metrics move from milliseconds to seconds.
This is particularly important for alerts. An alert configured with a threshold of 500 milliseconds cannot be copied unchanged if the new metric reports seconds.
Before enabling the new defaults, review:
Database dashboards and saved queries.
Connection-pool utilization alerts.
Query performance reports.
Database service dependency graphs.
Any custom processors that read database span attributes.
Also check whether dashboards group database services by server.address. The newer conventions distinguish the configured database target from the network endpoint actually contacted. For clustered databases, the configured target may represent multiple endpoints.
Review Changes to Messaging Traces
Messaging instrumentation requires special attention because the newer conventions affect both attribute names and trace structure.
Kafka is a useful example.
A previous trace might contain spans named:
orders publish
orders receive
orders process
The newer conventions use operation-oriented names:
send orders
poll orders
process orders
The messaging.operation attribute is also divided into two attributes:
messaging.operation.name
messaging.operation.type
For example, a Kafka poll operation can use poll as its operation name and receive as its operation type.
The changes are not limited to naming.
The relationship between producer and consumer spans can also change depending on whether receive spans are enabled and whether another span is already active when a message is processed.
Under the newer behavior, a processing span can become a child of the active application span and link to the producer span instead of using the producer span as its parent. This produces a different trace structure even when the same message is being processed.
For teams investigating message-processing delays, these differences matter. Queries that assume a particular parent-child relationship may no longer return the expected results.
Do not validate messaging migration by checking only span names. Inspect complete traces, including span kinds, links, parent relationships, and metric values.
Review Logging and Data Capture Defaults
The new defaults also affect which application log fields are captured.
For example, an application may use SLF4J structured key-value logging:
logger.info(
"Order processed",
keyValue("order.id", orderId),
keyValue("customer.tier", customerTier)
);
With the newer preview behavior, structured logging attributes can be captured automatically in supported instrumentation paths.
This can improve trace and log analysis, but it also changes the amount of data exported.
If the observability platform should capture only selected fields, configure an inclusion list:
OTEL_INSTRUMENTATION_COMMON_LOGGING_STRUCTURED_ATTRIBUTES_INCLUDED=order.id
An exclusion list can also be used to prevent sensitive fields from being exported.
Be careful when migrating older capture settings. The newer common inclusion and exclusion selectors support glob patterns. A wildcard can therefore capture substantially more data than an older literal-name configuration.
This matters for fields containing:
Telemetry should follow the same data-protection rules as application logs. More captured information is not automatically better observability.
Check Instrumentations That Are No Longer Enabled by Default
Some instrumentations that were previously enabled by default are turned off in the new preview behavior.
The affected integrations include:
Hibernate.
Hystrix.
Twilio.
If a Java application depends on one of these instrumentations, its spans may disappear after enabling the new defaults.
This does not necessarily mean the underlying library has stopped working. The agent may simply no longer instrument it automatically.
Review the application's dependency list and identify whether these integrations are needed. If they are, explicitly enable the relevant instrumentation using the configuration supported by the agent version.
For example, the agent provides instrumentation enablement controls. A configuration can be used to enable selected instrumentations rather than relying on the default set.
Test the resulting telemetry before deploying the configuration. Confirm that the expected spans are present and that enabling the instrumentation does not introduce duplicate spans.
Check Exporter Compatibility
Another important change concerns the Zipkin exporter.
Zipkin exporter support is removed when the combined 3.0 preview behavior is enabled. Applications using Zipkin should evaluate a move to OTLP before enabling the preview.
A typical OTLP configuration using an OpenTelemetry Collector might look like this:
OTEL_SERVICE_NAME=order-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
The Java agent can then export telemetry to the Collector, which can forward it to the configured observability backend.
Before changing exporters, verify the Collector receiver configuration, endpoint, protocol, authentication requirements, and network connectivity.
Also check whether the existing backend depends on Zipkin-specific behavior. Changing the exporter does not automatically migrate backend queries or dashboards.
Use Dual Emission to Compare Old and New Telemetry
One of the most useful migration techniques is dual emission.
It allows supported semantic convention groups to emit both old and new attributes during the evaluation period.
For example, database and code conventions can be tested using:
OTEL_SEMCONV_STABILITY_OPT_IN=database/dup,code/dup
Messaging can be evaluated separately:
OTEL_SEMCONV_STABILITY_PREVIEW=messaging/dup
This provides a way to compare the old and new attribute representations using actual application traffic.
However, dual emission has limitations. It does not preserve every old metric or both versions of every trace structure. Some metrics change names and units, and a span still has only one name and one kind.
Use dual emission as a comparison tool, not as a guarantee that the old and new telemetry are completely interchangeable.
Plan a Production Migration
A controlled migration should start with a baseline.
Capture representative traces, metrics, and logs before changing the agent. Record the dashboards, alert thresholds, and service maps that depend on the existing telemetry.
Then follow a staged process:
Deploy the preview agent in a development environment.
Enable the new database and code conventions using dual emission where supported.
Compare attribute names, values, types, and metric units.
Test messaging separately and inspect producer-consumer trace relationships.
Review log capture and sensitive-data filtering.
Check instrumentations that are no longer enabled by default.
Validate exporter and Collector compatibility.
Enable the combined preview and run integration tests.
Update dashboards and alerts using the new telemetry.
Deploy to a small production group before expanding the rollout.
Keep the previous agent version and configuration available during the migration. If important telemetry disappears or alerting becomes unreliable, the team should have a tested rollback path.
Conclusion
The OpenTelemetry Java agent 3.0 changes more than the way Java applications are instrumented. It updates semantic conventions, changes some metric names and units, modifies messaging trace relationships, and adjusts several capture and instrumentation defaults.
For production teams, the most important work is validating the telemetry consumed by dashboards, alerts, and downstream systems. A successful application startup does not prove that observability has migrated correctly.
Using the 2.32.0 preview, comparing old and new telemetry, and migrating one area at a time gives teams a practical way to prepare for the new defaults without losing visibility into their Java services.
Join the conversation! Your thoughts help the community grow.