Partager 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.

    Important

    Avant d’importer n’importe quoi d’autre, useAzureMonitor doit être appelé. Il peut y avoir une perte de télémétrie si d’autres bibliothèques sont importées en premier. 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.
  • Filtrer les dépendances, les journaux et les exceptions par nom d’opération ne sont pas encore pris en charge.

Modifications et limitations

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

Prise en charge de version de Node.js

Pour qu’une version de Node.js soit prise en charge par le Kit de développement logiciel (SDK) ApplicationInsights 3.X, elle doit avoir une prise en charge de à la fois le Kit de développement logiciel (SDK) Azure et de OpenTelemetry. 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. Le Kit de développement logiciel (SDK) ApplicationInsights dépend également du Kit de développement logiciel (SDK) Azure pour JS, qui ne garantit pas la prise en charge des versions Node.js qui ont atteint la fin de vie. Consultez la stratégie de prise en charge du Kit de développement logiciel (SDK) Azure pour JS. Pour qu’une version de Node.js soit prise en charge par le Kit de développement logiciel (SDK) ApplicationInsights 3.X, elle doit avoir une prise en charge de à la fois le Kit de développement logiciel (SDK) Azure et de OpenTelemetry.

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