Compartilhar via

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

  • Artigo

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

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

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

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

    npm uninstall applicationinsights

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

    Remova toda a instrumentação do Application Insights do 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 Distribuição do OpenTelemetry do Azure Monitor.

    Importante

    Antes de você importar qualquer outra coisa, useAzureMonitor deve ser chamado. Pode haver perda de telemetria se outras bibliotecas forem importadas primeiro. Siga a introdução à integração à Distribuição do OpenTelemetry do Azure Monitor.

Limitações e alterações de Distribuição do OpenTelemetry do Azure Monitor

  • As APIs do SDK 2.X do Application Insights não estão disponíveis na Distribuição do OpenTelemetry do Azure Monitor. Acesse essas APIs por meio de um caminho de atualização sem interrupção 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 compatível com o SDK do ApplicationInsights 3.X, ela deve ter suporte sobreposto do SDK do Azure e do OpenTelemetry. Verifique os runtimes com suporte do OpenTelemetry, para obter as atualizações mais recentes. Os usuários em versões mais antigas, como o Node 8, anteriormente com suporte pelo SDK do Application Insights, ainda podem usar soluções do OpenTelemetry, mas podem experimentar comportamentos inesperados ou de quebra. O SDK do ApplicationInsights também depende do SDK do Azure para JS, que não garante suporte para nenhuma versão Node.js que tenha atingido o 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 compatível com o 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 Distribuição do OpenTelemetry do Azure Monitor ou na atualização de versão principal para o SDK 3.X do Application Insights. Para encontrar essas alterações, juntamente com as opções que ainda oferecemos suporte, consulte a Documentação de configuração do SDK.

Métricas estendidas

Há suporte para métricas estendidas no SDK 2.X do Application Insights, no entanto, o suporte para essas métricas termina na versão 3.X do SDK do Application Insights e na Distribuição do OpenTelemetry do Azure Monitor.

Processadores de telemetria

Embora a Distribuição do OpenTelemetry do Azure Monitor e o SDK 3.X do Application Insights não ofereçam suporte aos TelemetryProcessors, eles permitem passar processadores de registro de extensão e log. Para obter mais informações sobre como, consulte o Projeto de Distribuição do OpenTelemetry do Azure Monitor.

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 da Distribuição do OpenTelemetry do Azure Monitor, para passar um SpanProcessor para a configuração da distribuição.

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);