Atualizando a partir do SDK Java 2.x do Application Insights

Artigo
10/14/2024

Normalmente, não há alterações de código ao atualizar para 3.x. As dependências do SDK 3.x são versões da API no-op das dependências do SDK 2.x. No entanto, quando usado com o agente Java 3.x, o agente Java 3.x fornece a implementação para eles. Como resultado, sua instrumentação personalizada é correlacionada com toda a nova autoinstrumentação fornecida pelo agente Java 3.x.

Etapa 1: Atualizar dependências

Dependência 2.x	Ação	Observações
`applicationinsights-core`	Atualizar a versão para `3.4.3` ou posterior
`applicationinsights-web`	Atualize a versão para `3.4.3` ou posterior e remova o filtro da Web do Application Insights seu `web.xml` arquivo.
`applicationinsights-web-auto`	Substituir por `3.4.3` ou posterior de `applicationinsights-web`
`applicationinsights-logging-log4j1_2`	Remova a dependência e remova o apêndice do Application Insights da configuração do Log4j.	Não é mais necessário, pois o Log4j 1.2 é autoinstrumentado no agente Java 3.x.
`applicationinsights-logging-log4j2`	Remova a dependência e remova o apêndice do Application Insights da configuração do Log4j.	Não é mais necessário, pois o Log4j 2 é autoinstrumentado no agente Java 3.x.
`applicationinsights-logging-logback`	Remova a dependência e remova o apêndice do Application Insights da configuração do Logback.	Não é mais necessário, pois o Logback é autoinstrumentado no agente Java 3.x.
`applicationinsights-spring-boot-starter`	Substituir por `3.4.3` ou posterior de `applicationinsights-web`	O nome da função de nuvem não é mais padrão para `spring.application.name`. Para saber como configurar o nome da função de nuvem, consulte os documentos de configuração 3.x.

Etapa 2: Adicionar o agente Java 3.x

Adicione o agente Java 3.x aos args de linha de comando da Java Virtual Machine (JVM), por exemplo:

-javaagent:path/to/applicationinsights-agent-3.6.2.jar

Se você estiver usando o agente Java do Application Insights 2.x, basta substituir o existente -javaagent:... pelo exemplo anterior.

Nota

Se você estava usando o spring-boot-starter e se preferir, há uma alternativa ao uso do agente Java. Consulte 3.x Spring Boot.

Etapa 3: Configurar a cadeia de conexão do Application Insights

Consulte configurando a cadeia de conexão.

Outras notas

O restante deste documento descreve as limitações e alterações que você pode encontrar ao atualizar de 2.x para 3.x e algumas soluções alternativas que você pode achar úteis.

TelemetryInitializers

2.x SDK TelemetryInitializers não são executados ao usar o agente 3.x. Muitos dos casos de uso que anteriormente exigiam escrever um TelemetryInitializer podem ser resolvidos no Application Insights Java 3.x configurando dimensões personalizadas. Ou usando atributos herdados.

TelemetryProcessors

2.x SDK TelemetryProcessors não são executados ao usar o agente 3.x. Muitos dos casos de uso que anteriormente exigiam escrever um TelemetryProcessor podem ser resolvidos no Application Insights Java 3.x configurando substituições de amostragem.

Vários aplicativos em uma única JVM

Este caso de uso é suportado no Application Insights Java 3.x usando substituições de nome de função de nuvem (visualização) e/ou substituições de cadeia de conexão (visualização).

Nomes das operações

No SDK Java 2.x do Application Insights, em alguns casos, os nomes das operações continham o caminho completo, por exemplo:

Captura de tela mostrando nomes de operação com caminho completo

Os nomes das operações no Application Insights Java 3.x foram alterados para geralmente fornecer uma melhor visualização agregada no Application Insights Portal U/X, por exemplo:

Captura de ecrã a mostrar nomes de operações parametrizados

No entanto, para alguns aplicativos, você ainda pode preferir a exibição agregada no U/X que foi fornecida pelos nomes de operação anteriores. Nesse caso, você pode usar o recurso de processadores de telemetria (visualização) em 3.x para replicar o comportamento anterior.

O trecho a seguir configura três processadores de telemetria que se combinam para replicar o comportamento anterior. Os processadores de telemetria executam as seguintes ações (na ordem):

O primeiro processador de telemetria é um processador de atributos (tem tipo attribute), o que significa que se aplica a toda a telemetria que tem atributos (atualmente requests e dependencies, mas em breve também traces).

Ele corresponde a qualquer telemetria que tenha atributos nomeados http.request.method e url.path.

Em seguida, ele extrai url.path o atributo em um novo atributo chamado tempName.
O segundo processador de telemetria é um processador span (tem tipo span), o que significa que se aplica a requests e dependencies.

Ele corresponde a qualquer extensão que tenha um atributo chamado tempPath.

Em seguida, ele atualiza o nome da extensão a partir do atributo tempPath.
O último processador de telemetria é um processador de atributos, do mesmo tipo do primeiro processador de telemetria.

Ele corresponde a qualquer telemetria que tenha um atributo chamado tempPath.

Em seguida, ele exclui o atributo chamado tempPath, e o atributo aparece como uma dimensão personalizada.

{
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.request.method" },
            { "key": "url.path" }
          ]
        },
        "actions": [
          {
            "key": "url.path",
            "pattern": "https?://[^/]+(?<tempPath>/[^?]*)",
            "action": "extract"
          }
        ]
      },
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "name": {
          "fromAttributes": [ "http.request.method", "tempPath" ],
          "separator": " "
        }
      },
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "actions": [
          { "key": "tempPath", "action": "delete" }
        ]
      }
    ]
  }
}

Exemplo de projeto

Este projeto Java 2.x SDK é migrado para um novo projeto usando o agente Java 3.x.

Partilhar via