ARMS Java agent v5.x breaking changes and migration guide-Application Real-Time Monitoring Service(ARMS)-阿里云帮助中心

Version information

The Java agent v5.x is built on OpenTelemetry Java Instrumentation and OTel semantic conventions, as detailed in the Java Agent Release Notes.

Semantic convention upgrade

Version 5.x fully adopts the OpenTelemetry (OTel) semantic convention, the de facto observability standard. OTel provides a rigorous, open, and continuously evolving data format adopted by most major providers.

As a major OTel contributor, Alibaba Cloud adopts this standard in v5.x to deliver:

Standardized observability data: Uniform data format with clear semantics, interoperable across observability vendors.
Enhanced ecosystem compatibility: Integrates with mainstream open-source and commercial observability tools through the OTel ecosystem.
Continuous evolution: Ongoing feature support as the OTel community grows.
More precise troubleshooting: Standardized data enables more accurate monitoring and diagnostics.

Important: Because of the semantic convention upgrade, some span attributes and behaviors have changed from v4.x. Read this document carefully before you upgrade.

OTel-related semantic changes

Changes to deprecated OTel span attributes

Version 5.x removes attributes that OTel has deprecated. The following are some deprecated HTTP attributes and their replacements.

http.method → http.request.method
http.status_code → http.response.status_code
http.url → url.full
http.scheme → url.scheme
net.peer.name → server.address
net.peer.port → server.port

Complete lists of deprecated attributes are in the following OTel specification documents:

Deprecated HTTP attributes: HTTP semantic conventions.

Deprecated database attributes: Database semantic conventions.

Deprecated RPC attributes: RPC semantic conventions.

Deprecated messaging attributes: Messaging semantic conventions.

Alibaba Cloud-related semantic changes

General changes

Aliyun span attribute adjustments

v4.x attribute	v5.x attribute	Description
`out.ids`	`destId`	Renamed. Value and function unchanged.
`component.name`	`call.type`	Renamed for clarity.
`rpc.type`	`rpcType`	Renamed to camelCase. Value and function unchanged.
`serviceType`	Removed	No longer supported.

These are custom Alibaba Cloud attributes that extend the OTel standard. Original attribute descriptions are in v4.x agent span attributes and resources.

HTTP plugin changes

1. HTTP client span name format change

Per the OTel specification, an HTTP client Span Name uses the format {method} {target}, where {target} corresponds to the url.template attribute. Because most upstream OTel components do not collect url.template, the v5.x agent uses url.full as the url.template by default, producing more descriptive span names than v4.x, which often showed only {method}.

Example of the change:

v4.x format: GET /get
v5.x format: GET http://httpbin.org/get

2. Vert.x-Web span count change

In v5.x, Vert.x-Web no longer records a separate span. Instead, it sets http.route on the server span, reducing the span count by one. This aligns with the upstream OTel agent.

3. Spring Cloud Gateway http.route collection change

Version 5.x instruments Spring Cloud Gateway. The server span's http.route is set to the route.id from the route configuration, and the span name follows the format {METHOD} {route.id}.

Attribute	v4.x behavior	v5.x behavior
Span Name	`GET /api/user/123` (Includes the full path, which can cause high cardinality.)	`GET user_service_route`
http.route	`/api/user/123` (Same as http.path, with uncontrolled cardinality.)	`user_service_route` (The configured route ID, which has low cardinality.)

This aligns with the upstream OTel agent (opentelemetry-java-instrumentation#9597). The agent uses route.id instead of path patterns because a single gateway route can have multiple path predicates. route.id provides a stable, low-cardinality identifier. The agent extracts the matched Route from ServerWebExchange, filters out auto-generated IDs (UUID format), and collects only explicitly configured route IDs.

Database plugin changes

1. General attribute adjustments

v4.x attribute	v5.x attribute	Description
`db.name`	`destId`	These fields are merged.
`sql`	`db.query.text`	Aligns with the OTel convention.
`op.type`	`db.operation.name`	Aligns with the OTel convention.
`db.bindValue`	`db.query.parameter.<index>`	Example: `db.query.parameter.0=value1`
`tableName`	Removed	Previously recorded only for relational databases. Now covered by the `db.query.text` attribute.

2. Redis and Lettuce plugin changes

Change

Description

The redis.args attribute is removed.

To view parameters, disable the sanitizer by setting:

otel.instrumentation.common.db-statement-sanitizer.enabled=false

The redis.command.key attribute is removed.

Represents the first command argument. Visible only when data sanitization is disabled.

3. response.size removal for Redis and Elasticsearch

The response.size attribute is removed in v5.x due to high collection overhead.

4. Parameter capture and SQL sanitization

If you enable parameter capture, SQL sanitization is disabled. This change requires an application restart.
The raw SQL statement toggle affects only traces. This change requires an application restart.

5. Change to DruidDataSource.getConnection instrumentation

Version 4.x used Druid-specific instrumentation for database connections. Version 5.x uses unified JDBC instrumentation, aligning with the OTel agent.

6. Endpoint attribute collection rules

The endpoint attribute is constructed using the following fallback sequence:

Concatenate server.address and server.port from the OTel semantic convention.
If unavailable, concatenate network.peer.address and network.peer.port.
If unavailable, fall back to the connection string.
If all methods fail, the endpoint defaults to Unknown.

Known limitations:

Scenario	Impact
Specific exception scenarios in Elasticsearch	When no response is received (such as connection refusal), server.address and server.port are unavailable, so the endpoint shows as `unknown`. This affects display only and does not impact trace navigation.
Lettuce versions earlier than 5.1 and versions 6.0.0 to 6.0.9	Plugin limitations prevent collection of server.address and server.port, so the endpoint shows as `unknown`. This affects display only and does not impact trace navigation. Upgrade to a later version to resolve this.

Scheduled task plugin changes

1. ElasticJob span attribute adjustments

v4.x attribute	v5.x attribute	Reason for change
`job.result.status`	Removed	Removed. v5.x reuses the OTel span status code.
`job.name`	`scheduling.apache-elasticjob.job.name`	Aligns with the OTel implementation.
`job.id`	`scheduling.apache-elasticjob.task.id`	Aligns with the OTel implementation.
`item`	`scheduling.apache-elasticjob.sharding.item.index`	Aligns with OTel. Value is now the current item index.
`shardingItemParameters`	`scheduling.apache-elasticjob.sharding.item.parameter`	Aligns with OTel. Value is now the parameter for the current item index.
`shardingTotalCount`	`scheduling.apache-elasticjob.sharding.total.count`	Aligns with the OTel implementation.
-	`job.system`	New attribute that aligns with the OTel implementation.

2. Spring scheduling span attribute adjustments

v4.x attribute	v5.x attribute	Reason for change
`job.id`	Removed	This information is now provided by the `code.namespace` and `code.function` attributes from the OTel implementation.
`job.name`	Removed	This information is now provided by the `code.namespace` and `code.function` attributes from the OTel implementation.
-	`job.system`	New attribute that aligns with the OTel implementation.

3. XXL-JOB span attribute adjustments

v4.x attribute	v5.x attribute	Reason for change
`job.result.status`	Removed	Removed. v5.x reuses the OTel span status code.
-	`scheduling.xxl-job.glue.type`	New attribute used to distinguish task types.
-	`scheduling.xxl-job.job.id`	New attribute recorded for script-type tasks.

4. Quartz span attribute adjustments

v4.x attribute	v5.x attribute	Reason for change
`job.result.status`	Removed	Removed. v5.x reuses the OTel span status code.
`group.id`	Removed	This information is now included in the span name.
`job.id`	Removed	This information is now included in the span name.

RPC plugin changes

gRPC error definition adjustment

Version 5.x refines the definition of gRPC errors.

Role	v4.x behavior	v5.x behavior
Client	All non-OK response codes are marked as errors.	All non-OK response codes are marked as errors (no change).
Server-side	All non-OK response codes are marked as errors.	Only six specific status codes are marked as errors on the server side.

Details are in the gRPC semantic conventions.

Messaging plugin changes

In v4.x, automatic environment fencing tag collection could cause data ambiguity. Version 5.x no longer collects this by default. A new system property, otel.instrumentation.messaging.common.broker_identifier, controls this behavior:

v4.x behavior

v5.x behavior

Description

producer destId

Default:

{brokerServerAddressList}@{Topic}

With toggle off:

{Topic}

Example:

[alikafka-post-cn-pe33gzedv005-1.alikafka.aliyuncs.com:9093,...]@YourTopic

Default:

{Topic}

With environment fencing enabled:

{environment fencing tag}@{Topic}

This change applies to the following plugins, which are instrumented by OpenTelemetry:

rocketmq-client
rabbitmq
spring-rabbit
kafka-clients
spring-kafka
jms

The behavior of the following plugins remains the same as in v4.x:

ons-client
paho-mqtt
mns

producer endpoint

Default:

{brokerServerAddressList}

With toggle off:

Unknown

Example:

[alikafka-post-cn-pe33gzedv005-1.alikafka.aliyuncs.com:9093,...]

Default:

Unknown

With environment fencing enabled:

{environment fencing tag}

consumer destId

Default:

{brokerServerAddressList}

With toggle off:

Unknown

Example:

[alikafka-post-cn-pe33gzedv005-1.alikafka.aliyuncs.com:9093,...]

Default:

Unknown

With environment fencing enabled:

{environment fencing tag}

consumer endpoint

Default:

{brokerServerAddressList}@{Topic}

With toggle off:

{Topic}

Example:

[alikafka-post-cn-pe33gzedv005-1.alikafka.aliyuncs.com:9093,...]@YourTopic

Default:

{Topic}

With environment fencing enabled:

{environment fencing tag}@{Topic}

Dynamic configuration changes

1. OTel specification attributes toggle

The "Record OpenTelemetry specification convention attributes" configuration is enabled by default.

Warning: In v5.x, this toggle cannot be disabled. Disabling this configuration prevents the agent from collecting some span attributes and impacts page navigation features.

2. "Maximum SQL statement length" configuration removed

The OTel agent enforces a built-in SQL length limit to prevent memory leaks: 32 KB in sanitization mode. In non-sanitization mode, control the limit with the otel.attribute.value.length.limit parameter.

Other

Co-deployment with other agents

The Alibaba Cloud Java agent does not support co-deployment with other agents, including the open-source OTel agent or agents from other vendors, such as SkyWalking.