Azure Monitor OpenTelemetry pour JavaScript

Mise en route

Installer le package

npm install @azure/monitor-opentelemetry

Environnements actuellement pris en charge

Avertissement: Ce SDK ne fonctionne que pour les environnements Node.js. Utilisez le SDK JavaScript Application Insights pour les scénarios web et de navigateur.

Pour plus d’informations, consultez notre de stratégie de support .

Conditions préalables

Activer le client OpenTelemetry Azure Monitor

Important:useAzureMonitor doit être appelé avant d’importer quoi que ce soit d’autre. Il peut y avoir une perte de télémétrie si d’autres bibliothèques sont importées en premier.

import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString:
      process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
  },
};
useAzureMonitor(options);

La chaîne de connexion peut être définie à l’aide de la variable APPLICATIONINSIGHTS_CONNECTION_STRINGd’environnement .

Paramétrage

import { resourceFromAttributes } from "@opentelemetry/resources";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

const resource = resourceFromAttributes({ testAttribute: "testValue" });
const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    // Offline storage
    storageDirectory: "c://azureMonitor",
    // Automatic retries
    disableOfflineStorage: false,
    // Application Insights Connection String
    connectionString:
      process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
  },
  samplingRatio: 1,
  instrumentationOptions: {
    // Instrumentations generating traces
    azureSdk: { enabled: true },
    http: { enabled: true },
    mongoDb: { enabled: true },
    mySql: { enabled: true },
    postgreSql: { enabled: true },
    redis: { enabled: true },
    redis4: { enabled: true },
    // Instrumentations generating logs
    bunyan: { enabled: true },
    winston: { enabled: true },
  },
  enableLiveMetrics: true,
  enableStandardMetrics: true,
  browserSdkLoaderOptions: {
    enabled: false,
    connectionString: "",
  },
  resource: resource,
  logRecordProcessors: [],
  spanProcessors: [],
};
useAzureMonitor(options);

Choix	Descriptif	Par défaut
`azureMonitorExporterOptions`	Configuration de l’exportateur OpenTelemetry Azure Monitor. Plus d’infos ici
`samplingRatio`	Le rapport d’échantillonnage doit prendre une valeur dans la plage [0,1], 1 signifiant que toutes les données seront échantillonnées et 0 que toutes les données de traçage seront échantillonnées.	`1`
`instrumentationOptions`	Configuration des bibliothèques d’instrumentation. Plus d’infos ici	`{ http: { enabled: true }, azureSdk: { enabled: true }, mongoDb: { enabled: true }, mySql: { enabled: true }, postgreSql: { enabled: true }, redis: { enabled: true }, redis4: { enabled: true }, bunyan: { enabled: false }, winston: { enabled: false } }`
`browserSdkLoaderOptions`	Autoriser la configuration des instruments Web.	`{ enabled: false, connectionString: "" }`
`resource`	Ressource Opentelemetry. Plus d’infos ici
`enableLiveMetrics`	Activer/désactiver les métriques en direct.	`true`
`enableStandardMetrics`	Activer/désactiver les métriques standard.	`true`
`logRecordProcessors`	Tableau de processeurs d’enregistrement de journaux à enregistrer auprès du fournisseur d’enregistrement global.
`spanProcessors`	Tableau de processeurs span à enregistrer auprès du fournisseur de traceur global.
`enableTraceBasedSamplingForLogs`	Activez l’échantillonnage des journaux en fonction de la trace.	`false`
`enablePerformanceCounters`	Activez les compteurs de performance.	`true`

Les options peuvent être définies à l’aide du fichier applicationinsights.json de configuration situé sous le dossier racine du dossier d’installation du @azure/monitor-opentelemetry paquet, Ex : node_modules/@azure/monitor-opentelemetry. Ces valeurs de configuration seront appliquées à toutes les instances AzureMonitorOpenTelemetryClient.

{
    "samplingRatio": 0.8,
    "enableStandardMetrics": true,
    "enableLiveMetrics": true,
    "instrumentationOptions":{
        "azureSdk": {
            "enabled": false
        }
    },
    ...
}

Un fichier JSON personnalisé peut être fourni à l’aide d’une variable d’environnement APPLICATIONINSIGHTS_CONFIGURATION_FILE .

process.env["APPLICATIONINSIGHTS_CONFIGURATION_FILE"] = "path/to/customConfig.json";

Bibliothèques d’instrumentation

Les bibliothèques d’instrumentation OpenTelemetry suivantes sont incluses dans le cadre d’Azure Monitor OpenTelemetry.

Note: Les instrumentations Azure SDK, MongoDB, MySQL, PostgreSQL, Redis et Redis-4 sont activées par défaut pour le traçage distribué. L’instrumentation HTTP/HTTPS est également activée par défaut. Toutes les autres instrumentations sont désactivées par défaut et peuvent être activées en réglant enabled: true les options d’instrumentation.

Avertissement: Les bibliothèques d’instrumentation sont basées sur les spécifications expérimentales d’OpenTelemetry. L’engagement de Microsoft en matière de support en préversion est de s’assurer que les bibliothèques suivantes émettent des données vers Azure Monitor Application Insights, mais il est possible que des modifications cassantes ou un mappage expérimental bloquent certains éléments de données.

Suivi distribué

Métriques

HTTP/HTTPS

Journaux

D’autres instrumentations OpenTelemetry sont disponibles ici et peuvent être ajoutées à l’aide de TracerProvider dans AzureMonitorOpenTelemetryClient.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { trace, metrics } from "@opentelemetry/api";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

useAzureMonitor();
registerInstrumentations({
  tracerProvider: trace.getTracerProvider(),
  meterProvider: metrics.getMeterProvider(),
  instrumentations: [new ExpressInstrumentation()],
});

Application Insights Browser SDK Loader

Application Insights Browser SDK Loader vous permet d’injecter le SDK web dans les réponses du serveur de nœuds lorsque les conditions suivantes sont remplies :

La réponse a un code d’état 200.
La méthode de réponse est GET.
La réponse du serveur a l’en-tête Conent-Type html.
Server resonse contient les balises et .
La réponse ne contient aucun point de terminaison CDN d’instrumentation web /backup actuels. (points de terminaison CDN d’instrumentation web actuels et de sauvegarde ici)

Vous trouverez de plus amples informations sur l’utilisation du chargeur SDK du navigateur ici.

Définir le nom du rôle cloud et l’instance de rôle cloud

Vous pouvez définir les attributs Nom du rôle cloud et Instance de rôle cloud via la ressource OpenTelemetry .

import { emptyResource } from "@opentelemetry/resources";
import {
  ATTR_SERVICE_NAME,
  SEMRESATTRS_SERVICE_NAMESPACE,
  SEMRESATTRS_SERVICE_INSTANCE_ID,
} from "@opentelemetry/semantic-conventions";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const customResource = emptyResource();
customResource.attributes[ATTR_SERVICE_NAME] = "my-helloworld-service";
customResource.attributes[SEMRESATTRS_SERVICE_NAMESPACE] = "my-namespace";
customResource.attributes[SEMRESATTRS_SERVICE_INSTANCE_ID] = "my-instance";

const options: AzureMonitorOpenTelemetryOptions = { resource: customResource };
useAzureMonitor(options);

Pour plus d’informations sur les attributs standard des ressources, consultez Conventions sémantiques des ressources.

Modifier la télémétrie

Cette section explique comment modifier la télémétrie.

Ajouter des attributs d’étendue

Pour ajouter des attributs span, utilisez l’une des deux méthodes suivantes :

Avec les options fournies par les bibliothèques d’instrumentation.
Ajout d’un processeur d’étendue personnalisé.

Ces attributs peuvent inclure l’ajout d’une propriété personnalisée à votre télémétrie.

Pourboire: L’avantage d’utiliser les options fournies par les bibliothèques d’instrumentation, lorsqu’elles sont disponibles, est que l’intégralité du contexte est disponible. Par conséquent, les utilisateurs peuvent choisir d’ajouter ou de filtrer davantage d’attributs. Par exemple, l’option enrichir de la bibliothèque d’instrumentation HttpClient permet aux utilisateurs d’accéder au httpRequestMessage lui-même. Ils peuvent sélectionner n’importe quoi et le stocker en tant qu’attribut.

Ajouter une propriété personnalisée à une trace

Tous les attributs que vous ajoutez aux étendues sont exportés en tant que propriétés personnalisées.

Utilisation d’un processeur personnalisé :

import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { Span } from "@opentelemetry/api";
import { SEMATTRS_HTTP_CLIENT_IP } from "@opentelemetry/semantic-conventions";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onStart(_span: Span): void {}
  onEnd(span: ReadableSpan): void {
    span.attributes["CustomDimension1"] = "value1";
    span.attributes["CustomDimension2"] = "value2";
    span.attributes[SEMATTRS_HTTP_CLIENT_IP] = "<IP Address>";
  }
}

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
  // Add the SpanEnrichingProcessor
  spanProcessors: [new SpanEnrichingProcessor()],
};

useAzureMonitor(options);

Ajouter le nom de l’opération aux traces et aux journaux

Utilisez un processeur de span personnalisé et un processeur d’enregistrement de journal afin d’attacher et de corréler le nom de l’opération à partir des demandes aux dépendances et aux journaux.

import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { Span, Context, trace } from "@opentelemetry/api";
import { AI_OPERATION_NAME } from "@azure/monitor-opentelemetry-exporter";
import { LogRecordProcessor, SdkLogRecord } from "@opentelemetry/sdk-logs";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onStart(_span: Span, _context: Context): void {
    const parentSpan = trace.getSpan(_context);
    if (parentSpan && "name" in parentSpan) {
      // If the parent span has a name we can assume it is a ReadableSpan and cast it.
      _span.setAttribute(AI_OPERATION_NAME, (parentSpan as unknown as ReadableSpan).name);
    }
  }
  onEnd(_span: ReadableSpan): void {}
}

class LogRecordEnrichingProcessor implements LogRecordProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onEmit(_logRecord: SdkLogRecord, _context: Context): void {
    const parentSpan = trace.getSpan(_context);
    if (parentSpan && "name" in parentSpan) {
      // If the parent span has a name we can assume it is a ReadableSpan and cast it.
      _logRecord.setAttribute(AI_OPERATION_NAME, (parentSpan as unknown as ReadableSpan).name);
    }
  }
}

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
  // Add the SpanEnrichingProcessor
  spanProcessors: [new SpanEnrichingProcessor()],
  logRecordProcessors: [new LogRecordEnrichingProcessor()],
};

useAzureMonitor(options);

Filtrer la télémétrie

Vous pouvez utiliser les méthodes suivantes pour filtrer les données de télémétrie avant qu’elles ne quittent votre application.

Excluez l’option URL fournie par de nombreuses bibliothèques d’instrumentation HTTP.

Vous trouverez ci-dessous un exemple de la façon d’exclure une URL d’un suivi à l’aide de la bibliothèque d’instrumentation HTTP/HTTPS.

import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
import { IncomingMessage, RequestOptions } from "node:http";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

const httpInstrumentationConfig: HttpInstrumentationConfig = {
  enabled: true,
  ignoreIncomingRequestHook: (request: IncomingMessage) => {
    // Ignore OPTIONS incoming requests
    if (request.method === "OPTIONS") {
      return true;
    }
    return false;
  },
  ignoreOutgoingRequestHook: (options: RequestOptions) => {
    // Ignore outgoing requests with /test path
    if (options.path === "/test") {
      return true;
    }
    return false;
  },
};

const options: AzureMonitorOpenTelemetryOptions = {
  instrumentationOptions: {
    http: httpInstrumentationConfig,
  },
};

useAzureMonitor(options);

Utilisez un processeur personnalisé. Vous pouvez utiliser un processeur d’étendues personnalisé pour exclure certaines étendues de l’exportation. Pour marquer des étendues à ne pas exporter, définissez leur TraceFlag sur DEFAULT. Utilisez l’exemple d’ajout de propriété personnalisée, mais remplacez les lignes de code suivantes :

import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { Span, Context, SpanKind, TraceFlags } from "@opentelemetry/api";

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Force flush code here
  }
  onStart(_span: Span, _parentContext: Context): void {
    // Normal code here
  }
  async shutdown(): Promise<void> {
    // Shutdown code here
  }
  onEnd(span: ReadableSpan): void {
    if (span.kind === SpanKind.INTERNAL) {
      span.spanContext().traceFlags = TraceFlags.NONE;
    }
  }
}

Télémétrie personnalisée

Cette section explique comment collecter des données de télémétrie personnalisées à partir de votre application.

Ajouter des métriques personnalisées

Vous pouvez collecter des métriques au-delà de ce qui est collecté par les bibliothèques d’instrumentation.

L’API OpenTelemetry propose six « instruments » de métriques pour couvrir une variété de scénarios de métriques, et vous devrez choisir le « type d’agrégation » approprié lors de la visualisation des métriques dans Metrics Explorer. Cette exigence est vraie lors de l’utilisation de l’API de métrique OpenTelemetry pour envoyer des métriques et lors de l’utilisation d’une bibliothèque d’instrumentation.

Le tableau suivant présente les types d’agrégation recommandés pour chacun des instruments métriques OpenTelemetry.

Instrumentation OpenTelemetry	Type d’agrégation Azure Monitor
Compteur	Somme
Compteur asynchrone	Somme
Histogramme	Moyenne, Somme, Nombre (Max, Min pour Python et Node.js uniquement)
Jauge asynchrone	Moyen
UpDownCounter (Python et Node.js uniquement)	Somme
UpDownCounter asynchrone (Python et Node.js uniquement)	Somme

Prudence: Les types d’agrégation au-delà de ce qui est affiché dans le tableau ne sont généralement pas significatifs.

La Spécification OpenTelemetry décrit les instruments et fournit des exemples de cas où vous pouvez utiliser chacun d’eux.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { metrics, ObservableResult } from "@opentelemetry/api";

useAzureMonitor();
const meter = metrics.getMeter("testMeter");

const histogram = meter.createHistogram("histogram");
const counter = meter.createCounter("counter");
const gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
  const randomNumber = Math.floor(Math.random() * 100);
  observableResult.observe(randomNumber, { testKey: "testValue" });
});

histogram.record(1, { testKey: "testValue" });
histogram.record(30, { testKey: "testValue2" });
histogram.record(100, { testKey2: "testValue" });

counter.add(1, { testKey: "testValue" });
counter.add(5, { testKey2: "testValue" });
counter.add(3, { testKey: "testValue2" });

Ajouter des exceptions personnalisées

Certaines bibliothèques d’instrumentation prennent automatiquement en charge les exceptions à Application Insights. Toutefois, vous pouvez signaler manuellement les exceptions au-delà de ce que les bibliothèques d’instrumentation rapportent. Par exemple, les exceptions interceptées par votre code ne sont généralement pas signalées, et vous pouvez les signaler et ainsi attirer l’attention sur elles dans des expériences pertinentes, y compris la lame des échecs et la vue des transactions de bout en bout.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { trace, Exception } from "@opentelemetry/api";

useAzureMonitor();
const tracer = trace.getTracer("testMeter");

const span = tracer.startSpan("hello");
try {
  throw new Error("Test Error");
} catch (error) {
  span.recordException(error as Exception);
}

Résolution des problèmes

Autodiagnostics

Azure Monitor OpenTelemetry utilise l’enregistreur d’API OpenTelemetry pour les journaux internes. Pour l’activer, utilisez le code suivant :

import { useAzureMonitor } from "@azure/monitor-opentelemetry";

process.env["APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL"] = "VERBOSE";
process.env["APPLICATIONINSIGHTS_LOG_DESTINATION"] = "file";
process.env["APPLICATIONINSIGHTS_LOGDIR"] = "path/to/logs";

useAzureMonitor();

APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVELenvironment peut être utilisée pour définir le niveau de journalisation souhaité, prenant en charge les valeurs suivantes : NONE, ERROR, WARN, INFODEBUGVERBOSE, et .ALL

Les journaux peuvent être placés dans un fichier local à l’aide de la variable d’environnement APPLICATIONINSIGHTS_LOG_DESTINATION , les valeurs prises en charge sont file et file+console, un fichier nommé applicationinsights.log sera généré par défaut dans le dossier tmp, y compris tous les journaux, /tmp pour *nix et USERDIR/AppData/Local/Temp pour Windows. Le répertoire des journaux peut être configuré à l’aide d’une variable d’environnement APPLICATIONINSIGHTS_LOGDIR .

Exemples

Pour obtenir des exemples complets de quelques scénarios de champion, consultez le samples/ dossier.

Concepts clés

Pour plus d’informations sur le projet OpenTelemetry, consultez les spécifications OpenTelemetry.

Registre des plugins

Pour voir si un plugin a déjà été créé pour une bibliothèque que vous utilisez, veuillez consulter le registre OpenTelemetry.

Si vous ne pouvez pas inscrire votre bibliothèque dans le registre, n’hésitez pas à suggérer une nouvelle demande de plugin à l’adresse opentelemetry-js-contrib.

Contribuer

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-11-14