Condividi tramite

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

  • Articolo

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.

  1. Acquisire familiarità con i prerequisiti dell'Application Programming Interface (API) e il Software Development Kit (SDK) JavaScript di OpenTelemetry.

  2. Disinstallare la dipendenza applicationinsights dal progetto.

    npm uninstall applicationinsights

  3. Rimuovere l'implementazione di SDK 2.X dal codice.

    Rimuovere tutta la strumentazione di Application Insights dal codice. Eliminare le sezioni in cui il client di Application Insights viene inizializzato, modificato o chiamato.

  4. Abilitare Application Insights con la distribuzione OpenTelemetry di Monitoraggio di Azure.

    Importante

    Prima di effettuare ulteriori importazioni, è necessario chiamare useAzureMonitor. Potrebbe verificarsi una perdita di dati di telemetria se altre librerie vengono importate per prime. Seguire Introduzione per eseguire l'onboarding nella distribuzione di OpenTelemetry di Monitoraggio di Azure.

Modifiche e limitazioni della distribuzione di OpenTelemetry di Monitoraggio di Azure

  • Le API di Application Insights SDK 2.X non sono disponibili nella distribuzione OpenTelemetry di Monitoraggio di Azure. È possibile accedere a queste API tramite un percorso di aggiornamento non interrotto in Application Insights SDK 3.X.
  • Il filtro delle dipendenze, dei log e delle eccezioni in base al nome dell'operazione non è ancora supportato.

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