Partilhar via

Migrar do SDK 2.X do Node.js Application Insights para o Azure Monitor OpenTelemetry

  • Artigo

Este guia fornece duas opções para atualizar do Azure Monitor Application Insights Node.js SDK 2.X para o OpenTelemetry.

  • Limpe a Node.js Distro OpenTelemetry do Monitor do Azure.
    • Remova as dependências da API clássica do Application Insights.
    • Familiarize-se com APIs e termos do OpenTelemetry .
    • Posicione-se para usar tudo o que a OpenTelemetry oferece agora e no futuro.
  • Atualize para o Node.js SDK 3.X.
    • Adie as alterações de código, preservando a compatibilidade com eventos e métricas personalizados existentes.
    • Aceda a bibliotecas de instrumentação OpenTelemetry mais avançadas.
    • Mantenha a elegibilidade para as correções de bugs e de segurança mais recentes.

  1. Obtenha conhecimento prévio da Interface de Programação de Aplicativos (API) JavaScript OpenTelemetry e do Software Development Kit (SDK).

  2. Desinstale a applicationinsights dependência do seu projeto.

    npm uninstall applicationinsights

  3. Remova a implementação do SDK 2.X do seu código.

    Remova toda a instrumentação do Application Insights do seu código. Exclua todas as seções em que o cliente do Application Insights é inicializado, modificado ou chamado.

  4. Habilite o Application Insights com a Distro OpenTelemetry do Azure Monitor.

    Importante

    Antes de importar qualquer outra coisa, useAzureMonitor deve ser chamado. Pode haver perda de telemetria se outras bibliotecas forem importadas primeiro. Siga os primeiros passos para integrar a Distro OpenTelemetry do Azure Monitor.

Alterações e limitações do Azure Monitor OpenTelemetry Distro

  • As APIs do SDK 2.X do Application Insights não estão disponíveis na Distro OpenTelemetry do Azure Monitor. Você pode acessar essas APIs por meio de um caminho de atualização ininterrupto no SDK 3.X do Application Insights.
  • Ainda não há suporte para a filtragem de dependências, logs e exceções por nome de operação.

Alterações e limitações

As alterações e limitações a seguir se aplicam a ambos os caminhos de atualização.

Suporte à versão Node.js

Para que uma versão do Node.js seja suportada pelo SDK do ApplicationInsights 3.X, ela deve ter suporte sobreposto do SDK do Azure e do OpenTelemetry. Verifique os tempos de execução suportados pelo OpenTelemetry para obter as atualizações mais recentes. Os usuários em versões mais antigas, como o Node 8, anteriormente suportado pelo SDK do ApplicationInsights, ainda podem usar soluções OpenTelemetry mas podem experimentar um comportamento inesperado ou de quebra. O SDK do ApplicationInsights também depende do SDK do Azure para JS, que não garante suporte para Node.js versões que tenham chegado ao fim da vida útil. Consulte a política de suporte do SDK do Azure para JS. Para que uma versão do Node.js seja suportada pelo SDK do ApplicationInsights 3.X, ela deve ter suporte sobreposto do SDK do Azure e do OpenTelemetry.

Opções de configuração

O SDK do Application Insights versão 2.X oferece opções de configuração que não estão disponíveis na Distro OpenTelemetry do Azure Monitor ou na atualização da versão principal para o SDK 3.X do Application Insights. Para encontrar essas alterações, juntamente com as opções que ainda suportamos, consulte a documentação de configuração do SDK.

Métricas estendidas

As métricas estendidas são suportadas no SDK 2.X do Application Insights; no entanto, o suporte para essas métricas termina na versão 3.X do SDK do ApplicationInsights e na Distro OpenTelemetry do Azure Monitor.

Processadores de Telemetria

Embora o Azure Monitor OpenTelemetry Distro e o Application Insights SDK 3.X não ofereçam suporte a TelemetryProcessors, eles permitem que você passe span e registre processadores. Para obter mais informações sobre como, consulte Azure Monitor OpenTelemetry Distro project.

Este exemplo mostra o equivalente a criar e aplicar um processador de telemetria que anexa uma propriedade personalizada no SDK 2.X do Application Insights.

const applicationInsights = require("applicationinsights");
applicationInsights.setup("YOUR_CONNECTION_STRING");
applicationInsights.defaultClient.addTelemetryProcessor(addCustomProperty);
applicationInsights.start();

function addCustomProperty(envelope: EnvelopeTelemetry) {
    const data = envelope.data.baseData;
    if (data?.properties) {
        data.properties.customProperty = "Custom Property Value";
    }
    return true;
}

Este exemplo mostra como modificar uma implementação do Azure Monitor OpenTelemetry Distro para passar um SpanProcessor para a configuração da distro.

import { Context, Span} from "@opentelemetry/api";
import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

class SpanEnrichingProcessor implements SpanProcessor {
    forceFlush(): Promise<void> {
        return Promise.resolve();
    }
    onStart(span: Span, parentContext: Context): void {
        return;
    }
    onEnd(span: ReadableSpan): void {
        span.attributes["custom-attribute"] = "custom-value";
    }
    shutdown(): Promise<void> {
        return Promise.resolve();
    }
}

const options = {
    azureMonitorExporterOptions: {
        connectionString: "YOUR_CONNECTION_STRING"
    },
    spanProcessors: [new SpanEnrichingProcessor()],
};
useAzureMonitor(options);