Eseguire la migrazione da Node.js di Application Insights SDK 2.X a OpenTelemetry di Monitoraggio di Azure

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

• Effettuare l'installazione pulita della distribuzione di 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.
  • Posizionarsi per usare tutte le offerte OpenTelemetry ora e in futuro.
• Eseguire l'aggiornamento a Node.js SDK 3.X.
  • 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

Application Insights SDK versione 2.X offre opzioni di configurazione non disponibili nella distribuzione OpenTelemetry di Monitoraggio di Azure o nell'aggiornamento della versione principale ad Application Insights SDK 3.X. 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 di OpenTelemetry e Application Insights SDK 3.X di Monitoraggio di Azure non supportano TelemetryProcessor, consentono di passare processori di record di intervallo e di log. Per altre informazioni sulle modalità, vedere Progetto di distribuzione OpenTelemetry di Monitoraggio di Azure.

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