Eseguire la migrazione dall'SDK Application Insights 2.X per Node.js ad Azure Monitor OpenTelemetry

Questa guida offre due opzioni per eseguire l'aggiornamento dall'SDK Node.js 2.X di Azure Monitor Application Insights a OpenTelemetry.

• Effettuare l'installazione pulita della distribuzione OpenTelemetry di Monitoraggio di Azure Node.js.
  • Rimuovere le dipendenze dall'API classica di Application Insights.
  • Acquisire familiarità con le API e i termini OpenTelemetry.
  • Posizionati per sfruttare tutto ciò che OpenTelemetry offre ora e in futuro.
• Eseguire l'aggiornamento all'SDK 3.X di Node.js.
  • Posticipare le modifiche al codice mantenendo la compatibilità con gli eventi e le metriche personalizzati esistenti.
  • Accedere a librerie di strumentazione OpenTelemetry più avanzate.
  • Mantenere l'idoneità per le correzioni di bug e sicurezza più recenti.

Modifiche e limitazioni

Le modifiche e le limitazioni seguenti si applicano a entrambi i percorsi di aggiornamento.

Supporto della versione di Node.js

Affinché una versione di Node.js sia supportata da ApplicationInsights 3.X SDK, deve avere un supporto sovrapposto sia da Azure SDK che da OpenTelemetry. Controllare i runtime supportati da OpenTelemetry per gli aggiornamenti più recenti. Gli utenti con versioni precedenti come Node 8, precedentemente supportati da ApplicationInsights SDK, possono comunque usare soluzioni OpenTelemetry, ma possono riscontrare un comportamento imprevisto o di interruzione. ApplicationInsights SDK dipende anche da Azure SDK per JS, che non garantisce il supporto per le versioni Node.js che hanno raggiunto la fine del ciclo di vita. Vedere i criteri di supporto di Azure SDK per JS. Affinché una versione di Node.js sia supportata da ApplicationInsights 3.X SDK, deve avere un supporto sovrapposto sia da Azure SDK che da OpenTelemetry.

Opzioni di configurazione

La versione 2.X dell'SDK di Application Insights offre opzioni di configurazione non disponibili nella distribuzione OpenTelemetry di Monitoraggio di Azure o nell'aggiornamento della versione principale della versione 3.X dell'SDK di Application Insights. Per trovare queste modifiche, insieme alle opzioni ancora supportate, vedere la documentazione sulla configurazione dell'SDK.

Metriche estese

Le metriche estese sono supportate in Application Insights SDK 2.X. Tuttavia, il supporto per queste metriche termina sia nella versione 3.X di ApplicationInsights SDK sia nella distribuzione OpenTelemetry di Monitoraggio di Azure.

Processori di telemetria

Anche se la distribuzione OpenTelemetry di Monitoraggio di Azure e la versione 3.X dell'SDK di Application Insights non supportano TelemetryProcessors, consentono di passare processori di record di intervallo e di log. Per ulteriori informazioni su come procedere, vedere il progetto OpenTelemetry Distro di Azure Monitor.

Questo esempio mostra l'equivalente della creazione e dell'applicazione di un processore di telemetria che collega una proprietà personalizzata in Application Insights SDK 2.X.

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

Questo esempio illustra come modificare un'implementazione della distribuzione OpenTelemetry di Monitoraggio di Azure per trasferire uno SpanProcessor alla configurazione della distribuzione.

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