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

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.

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