ARMS Java agent v5.x breaking changes and migration guide - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

Informações da versão

O Java agent v5.x baseia-se no OpenTelemetry Java Instrumentation e nas convenções semânticas do OTel, conforme detalhado nas Notas de lançamento do Java Agent.

Atualização da convenção semântica

A versão 5.x adota integralmente a convenção semântica do OpenTelemetry (OTel), o padrão de facto para observabilidade. O OTel oferece um formato de dados rigoroso, aberto e em constante evolução, utilizado pela maioria dos principais provedores.

Como grande contribuidor do OTel, a Alibaba Cloud incorpora esse padrão na versão 5.x para proporcionar:

Dados de observabilidade padronizados: Formato uniforme com semântica clara, garantindo interoperabilidade entre fornecedores de observabilidade.
Maior compatibilidade com o ecossistema: Integração com as principais ferramentas comerciais e open source de observabilidade por meio do ecossistema OTel.
Evolução contínua: Suporte constante a novos recursos à medida que a comunidade OTel se expande.
Solução de problemas mais precisa: Dados padronizados permitem monitoramento e diagnósticos mais precisos.

Importante : Devido à atualização da convenção semântica, alguns atributos de span e comportamentos mudaram em relação à versão 4.x. Leia este documento atentamente antes de atualizar.

Alterações semânticas relacionadas ao OTel

Mudanças em atributos de span OTel descontinuados

A versão 5.x remove atributos descontinuados pelo OTel. A seguir, listamos alguns atributos HTTP obsoletos e seus substitutos.

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

As listas completas de atributos descontinuados estão disponíveis nos seguintes documentos de especificação do OTel:

Atributos HTTP descontinuados: Convenções semânticas HTTP .

Atributos de banco de dados descontinuados: Convenções semânticas de banco de dados .

Atributos RPC descontinuados: Convenções semânticas RPC .

Atributos de mensagens descontinuados: Convenções semânticas de mensagens .

Alterações semânticas relacionadas à Alibaba Cloud

Alterações gerais

Ajustes em atributos de span Aliyun

Atributo v4.x	Atributo v5.x	Descrição
`out.ids`	`destId`	Renomeado. Valor e função permanecem inalterados.
`component.name`	`call.type`	Renomeado para maior clareza.
`rpc.type`	`rpcType`	Renomeado para camelCase. Valor e função permanecem inalterados.
`serviceType`	Removido	Não há mais suporte.

Estes são atributos personalizados da Alibaba Cloud que estendem o padrão OTel. As descrições originais dos atributos encontram-se em Atributos de span e recursos do agent v4.x .

Alterações no plugin HTTP

1. Mudança no formato do nome de span do cliente HTTP

De acordo com a especificação OTel, o Span Name de um cliente HTTP utiliza o formato {method} {target}, onde {target} corresponde ao atributo url.template. Como a maioria dos componentes OTel upstream não coleta url.template, o agent v5.x usa url.full como url.template por padrão. Isso gera nomes de span mais descritivos do que na versão 4.x, que frequentemente exibia apenas {method}.

Exemplo da alteração:

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

2. Alteração na contagem de spans do Vert.x-Web

Na versão 5.x, o Vert.x-Web deixa de registrar um span separado. Em vez disso, defina http.route no span do servidor, reduzindo a contagem total de spans em uma unidade. Esse comportamento está alinhado com o agent OTel upstream.

3. Mudança na coleta de http.route no Spring Cloud Gateway

A versão 5.x instrumenta o Spring Cloud Gateway. O atributo http.route do span do servidor é definido com o route.id da configuração de rota, e o nome do span segue o formato {METHOD} {route.id}.

Atributo	Comportamento v4.x	Comportamento v5.x
Span Name	`GET /api/user/123` (Inclui o caminho completo, o que pode causar alta cardinalidade.)	`GET user_service_route`
http.route	`/api/user/123` (Igual a http.path, com cardinalidade não controlada.)	`user_service_route` (O ID da rota configurada, que possui baixa cardinalidade.)

Essa mudança alinha o comportamento ao agent OTel upstream (opentelemetry-java-instrumentation#9597). O agent utiliza route.id em vez de padrões de caminho porque uma única rota de gateway pode ter múltiplos predicados de caminho. O route.id fornece um identificador estável e de baixa cardinalidade. O agent extrai a Rota correspondente de ServerWebExchange, filtra IDs gerados automaticamente (formato UUID) e coleta apenas os IDs de rota configurados explicitamente.

Alterações no plugin de banco de dados

1. Ajustes gerais de atributos

Atributo v4.x	Atributo v5.x	Descrição
`db.name`	`destId`	Campos mesclados.
`sql`	`db.query.text`	Alinhado com a convenção OTel.
`op.type`	`db.operation.name`	Alinhado com a convenção OTel.
`db.bindValue`	`db.query.parameter.<index>`	Exemplo: `db.query.parameter.0=value1`
`tableName`	Removido	Anteriormente registrado apenas para bancos relacionais. Agora coberto pelo atributo `db.query.text`.

2. Alterações nos plugins Redis e Lettuce

Alteração

Descrição

O atributo redis.args foi removido.

Para visualizar parâmetros, desative o sanitizador definindo:

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

O atributo redis.command.key foi removido.

Representa o primeiro argumento do comando. Visível somente quando a sanitização de dados está desativada.

3. Remoção de response.size para Redis e Elasticsearch

O atributo response.size foi removido na versão 5.x devido ao alto custo de coleta.

4. Captura de parâmetros e sanitização de SQL

Ao ativar a captura de parâmetros, a sanitização de SQL é desativada. Essa alteração exige reinicialização da aplicação.
A opção de instrução SQL bruta afeta apenas traces. Essa alteração exige reinicialização da aplicação.

5. Mudança na instrumentação de DruidDataSource.getConnection

A versão 4.x utilizava instrumentação específica do Druid para conexões de banco de dados. A versão 5.x adota uma instrumentação JDBC unificada, alinhando-se ao agent OTel.

6. Regras de coleta do atributo endpoint

O atributo endpoint é construído seguindo esta sequência de fallback:

Concatenação de server.address e server.port da convenção semântica OTel.
Se indisponível, concatenação de network.peer.address e network.peer.port.
Caso também falhe, uso da string de conexão.
Se todos os métodos falharem, o endpoint assume o valor padrão Unknown.

Limitações conhecidas:

Cenário	Impacto
Cenários específicos de exceção no Elasticsearch	Quando nenhuma resposta é recebida (como recusa de conexão), server.address e server.port ficam indisponíveis, fazendo com que o endpoint seja exibido como `unknown`. Isso afeta apenas a visualização e não impacta a navegação de traces.
Versões do Lettuce anteriores a 5.1 e versões 6.0.0 a 6.0.9	Limitações do plugin impedem a coleta de server.address e server.port, resultando na exibição do endpoint como `unknown`. Isso afeta apenas a visualização e não impacta a navegação de traces. Atualize para uma versão posterior para resolver o problema.

Alterações no plugin de tarefas agendadas

1. Ajustes em atributos de span do ElasticJob

Atributo v4.x	Atributo v5.x	Motivo da alteração
`job.result.status`	Removido	Eliminado. A v5.x reutiliza o código de status de span do OTel.
`job.name`	`scheduling.apache-elasticjob.job.name`	Alinhado com a implementação OTel.
`job.id`	`scheduling.apache-elasticjob.task.id`	Alinhado com a implementação OTel.
`item`	`scheduling.apache-elasticjob.sharding.item.index`	Alinhado com OTel. O valor agora é o índice do item atual.
`shardingItemParameters`	`scheduling.apache-elasticjob.sharding.item.parameter`	Alinhado com OTel. O valor agora é o parâmetro do índice do item atual.
`shardingTotalCount`	`scheduling.apache-elasticjob.sharding.total.count`	Alinhado com a implementação OTel.
-	`job.system`	Novo atributo alinhado com a implementação OTel.

2. Ajustes em atributos de span do Spring scheduling

Atributo v4.x	Atributo v5.x	Motivo da alteração
`job.id`	Removido	Esta informação agora é fornecida pelos atributos `code.namespace` e `code.function` da implementação OTel.
`job.name`	Removido	Esta informação agora é fornecida pelos atributos `code.namespace` e `code.function` da implementação OTel.
-	`job.system`	Novo atributo alinhado com a implementação OTel.

3. Ajustes em atributos de span do XXL-JOB

Atributo v4.x	Atributo v5.x	Motivo da alteração
`job.result.status`	Removido	Eliminado. A v5.x reutiliza o código de status de span do OTel.
-	`scheduling.xxl-job.glue.type`	Novo atributo usado para distinguir tipos de tarefas.
-	`scheduling.xxl-job.job.id`	Novo atributo registrado para tarefas do tipo script.

4. Ajustes em atributos de span do Quartz

Atributo v4.x	Atributo v5.x	Motivo da alteração
`job.result.status`	Removido	Eliminado. A v5.x reutiliza o código de status de span do OTel.
`group.id`	Removido	Esta informação agora está incluída no nome do span.
`job.id`	Removido	Esta informação agora está incluída no nome do span.

Alterações no plugin RPC

Ajuste na definição de erros gRPC

A versão 5.x refina a definição de erros gRPC.

Função	Comportamento v4.x	Comportamento v5.x
Cliente	Todos os códigos de resposta diferentes de OK são marcados como erros.	Todos os códigos de resposta diferentes de OK são marcados como erros (sem alterações).
Lado do servidor	Todos os códigos de resposta diferentes de OK são marcados como erros.	Apenas seis códigos de status específicos são marcados como erros no lado do servidor.

Os detalhes estão disponíveis nas Convenções semânticas gRPC .

Alterações no plugin de mensagens

Na versão 4.x, a coleta automática de tags de isolamento de ambiente podia causar ambiguidade nos dados. A versão 5.x deixa de coletar essa informação por padrão. Uma nova propriedade de sistema, otel.instrumentation.messaging.common.broker_identifier, controla esse comportamento:

Comportamento v4.x

Comportamento v5.x

Descrição

producer destId

Padrão:

{brokerServerAddressList}@{Topic}

Com opção desativada:

{Topic}

Exemplo:

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

Padrão:

{Topic}

Com isolamento de ambiente ativado:

{environment fencing tag}@{Topic}

Esta alteração aplica-se aos seguintes plugins, que são instrumentados pelo OpenTelemetry:

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

O comportamento dos seguintes plugins permanece igual ao da v4.x:

ons-client
paho-mqtt
mns

producer endpoint

Padrão:

{brokerServerAddressList}

Com opção desativada:

Unknown

Exemplo:

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

Padrão:

Unknown

Com isolamento de ambiente ativado:

{environment fencing tag}

consumer destId

Padrão:

{brokerServerAddressList}

Com opção desativada:

Unknown

Exemplo:

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

Padrão:

Unknown

Com isolamento de ambiente ativado:

{environment fencing tag}

consumer endpoint

Padrão:

{brokerServerAddressList}@{Topic}

Com opção desativada:

{Topic}

Exemplo:

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

Padrão:

{Topic}

Com isolamento de ambiente ativado:

{environment fencing tag}@{Topic}

Alterações na configuração dinâmica

1. Opção de atributos da especificação OTel

A configuração "Record OpenTelemetry specification convention attributes" vem ativada por padrão.

Aviso : Na v5.x, esta opção não pode ser desativada. Desabilitar essa configuração impede que o agent colete certos atributos de span e afeta os recursos de navegação de páginas.

2. Remoção da configuração "Maximum SQL statement length"

O agent OTel impõe um limite interno de tamanho de SQL para evitar vazamentos de memória: 32 KB no modo de sanitização. No modo sem sanitização, controle o limite através do parâmetro otel.attribute.value.length.limit.

Outros

Implantação conjunta com outros agents

O Java agent da Alibaba Cloud não suporta implantação conjunta com outros agents, incluindo o agent OTel open source ou agents de outros fornecedores, como o SkyWalking.