Partage via

Migrez du kit de développement logiciel (SDK) 2.X Node.js Application Insights vers Azure Monitor OpenTelemetry

  • Article

Ce guide fournit deux options pour la mise à niveau du Kit de développement logiciel (SDK) 2.X Node.js Azure Monitor Application Insights vers OpenTelemetry.

  • Réinstallez la distribution OpenTelemetry Azure Monitor Node.js.
    • Supprimez les dépendances de l’API classique Application Insights.
    • Familiarisez-vous avec les API et les conditions générales OpenTelemetry.
    • Positionnez-vous de manière à utiliser toutes les offres OpenTelemetry maintenant et à l’avenir.
  • Effectuez la mise à niveau vers le Kit de développement logiciel (SDK) 3.X Node.js.
    • Reportez les modifications de code tout en préservant la compatibilité avec les événements et métriques personnalisés existants.
    • Accédez à des bibliothèques d’instrumentation OpenTelemetry plus riches.
    • Conservez l’éligibilité pour les derniers correctifs de sécurité et de bogues.

  1. Obtenez les connaissances préalables sur l’interface de programmation d’applications (API) et le Kit de développement logiciel (SDK). JavaScript OpenTelemetry.

  2. Désinstallez la dépendance applicationinsights de votre projet.

    npm uninstall applicationinsights

  3. Supprimez l’implémentation du Kit de développement logiciel (SDK) 2.X de votre code.

    Supprimez toutes les instrumentations Application Insights de votre code. Supprimez les sections dans lesquelles le client Application Insights est initialisé, modifié ou appelé.

  4. Activez Application Insights avec la distribution OpenTelemetry Azure Monitor.

    Suivez Bien démarrer pour intégrer la distribution Azure Monitor OpenTelemetry.

Modifications et limites de distribution d’Azure Monitor OpenTelemetry

Les API du Kit de développement logiciel (SDK) 2.X Application Insights ne sont pas disponibles dans la distribution Azure Monitor OpenTelemetry. Vous pouvez accéder à ces API par le biais d’un chemin d’accès de mise à niveau permanent dans le Kit de développement logiciel (SDK) 3.X Application Insights.

Modifications et limitations

Les modifications et limites suivantes s’appliquent aux deux chemins d’accès de mise à niveau.

Prise en charge de Node < 14

Les solutions de monitoring d’OpenTelemetry JavaScript ne prennent officiellement en charge que Node 14 et versions ultérieures. Examinez les runtimes pris en charge par OpenTelemetry pour prendre connaissance des dernières mises à jour. Les utilisateurs de versions antérieures comme Node 8, auparavant pris en charge par le Kit de développement logiciel (SDK) Application Insights, peuvent toujours utiliser des solutions OpenTelemetry, mais peuvent rencontrer un comportement inattendu ou instable.

Options de configuration

Le Kit de développement logiciel (SDK) version 2.X Application Insights offre des options de configuration qui ne sont pas disponibles dans la distribution Azure Monitor OpenTelemetry ou dans la mise à niveau de version majeure vers le Kit de développement logiciel (SDK) 3.X Application Insights. Pour accéder à ces modifications, ainsi qu’aux options que nous prenons toujours en charge, consultez la documentation de configuration du Kit de développement logiciel (SDK).

Métriques étendues

Les métriques étendues sont prises en charge dans le Kit de développement logiciel (SDK) 2.X Application Insights. Toutefois, elles ne sont plus disponibles dans la version 3.X du Kit de développement logiciel (SDK) Application Insights et dans la distribution Azure Monitor OpenTelemetry.

Processeurs de télémétrie

Bien que la distribution Azure Monitor OpenTelemetry et le Kit de développement logiciel (SDK) 3.X Application Insights ne prennent pas en charge TelemetryProcessors, ils vous permettent de passer des processeurs d’enregistrements span et log. Pour plus d’informations sur la méthode, consultez Projet de distribution Azure Monitor OpenTelemetry.

Cet exemple montre l’équivalent de la création et de l’application d’un processeur de télémétrie qui attache une propriété personnalisée dans le Kit de développement logiciel (SDK) 2.X 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;
}

Cet exemple montre comment modifier une implémentation de distribution Azure Monitor OpenTelemetry pour envoyer un SpanProcessor à la configuration de la distribution.

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