Azure Monitor OpenTelemetry pour JavaScript

Prise en main

Installer le package

npm install @azure/monitor-opentelemetry

Environnements actuellement pris en charge

• Versions LTS de Node.js

• Runtimes pris en charge par OpenTelemetry

Avertissement: Ce Kit de développement logiciel (SDK) fonctionne uniquement pour les environnements Node.js. Utilisez le SDK JavaScript Application Insights pour les scénarios web et navigateur.

Pour plus d’informations, consultez notre politique de support .

Prérequis

• Un abonnement Azure
• Espace de travail Application Insights

Activer le client Azure Monitor OpenTelemetry

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 résultante si d’autres bibliothèques sont importées en premier.

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } 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 d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING

Configuration

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

const resource = new Resource({ "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);

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 package, par exemple . 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 APPLICATIONINSIGHTS_CONFIGURATION_FILE variable d’environnement.

process.env.APPLICATIONINSIGHTS_CONFIGURATION_FILE = "C:/applicationinsights/config/customConfig.json"

// Application Insights SDK setup....

Bibliothèques d’instrumentation

Les bibliothèques OpenTelemetry Instrumentation suivantes sont incluses dans Azure Monitor OpenTelemetry.

Avertissement: Les bibliothèques d’instrumentation sont basées sur des spécifications OpenTelemetry expérimentales. L’engagement de prise en charge de la préversion par Microsoft permet de s’assurer que les bibliothèques listées ci-dessous émettent des données pour Azure Monitor Application Insights, mais il est possible que des modifications avec rupture ou qu’un mappage expérimental bloquent certains éléments de données.

Suivi distribué

• HTTP/HTTPS
• MongoDB
• MySQL
• Postgres
• Redis
• Redis-4
• Kit de développement logiciel (SDK) Azure

Mesures

• HTTP/HTTPS

Journaux d’activité

• Bunyan

• Winston

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 { metrics, trace } from "@opentelemetry/api";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

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

Chargeur du Kit de développement logiciel (SDK) Du navigateur Application Insights

Application Insights Browser SDK Loader vous permet d’injecter le KIT de développement logiciel (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.
• Le serveur resonse contient à la fois 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)

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

Vous pouvez définir le nom du rôle cloud et l’instance de rôle cloud via les attributs de ressource OpenTelemetry .

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";

// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const customResource = Resource.EMPTY;
customResource.attributes[SemanticResourceAttributes.SERVICE_NAME] = "my-helloworld-service";
customResource.attributes[SemanticResourceAttributes.SERVICE_NAMESPACE] = "my-namespace";
customResource.attributes[SemanticResourceAttributes.SERVICE_INSTANCE_ID] = "my-instance";

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

Pour plus d’informations sur les attributs standard pour les 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.

Pointe: L’avantage de l’utilisation des options fournies par les bibliothèques d’instrumentation, lorsqu’elles sont disponibles, est que l’ensemble 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.

Ajoutez 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 { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
import { SemanticAttributes } from "@opentelemetry/semantic-conventions";


class SpanEnrichingProcessor implements SpanProcessor{
  forceFlush(): Promise<void>{
    return Promise.resolve();
  }
  shutdown(): Promise<void>{
    return Promise.resolve();
  }
  onStart(_span: Span): void{}
  onEnd(span: ReadableSpan){
    span.attributes["CustomDimension1"] = "value1";
    span.attributes["CustomDimension2"] = "value2";
    span.attributes[SemanticAttributes.HTTP_CLIENT_IP] = "<IP Address>";
  }
}

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

Filtrer les données de 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.

1. Option d’exclusion d’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 { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
   import { IncomingMessage } from "http";
   import { RequestOptions } from "https";
   import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
   
   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);
   

2. Utiliser 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 d’une propriété personnalisée, mais changez les lignes de code suivantes :

   ...
   import { SpanKind, TraceFlags } from "@opentelemetry/api";
   import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
   
   class SpanEnrichingProcessor implements SpanProcessor {
       ...
   
       onEnd(span: ReadableSpan) {
           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.

Ajoutez 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 divers scénarios de métrique et vous devez 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 de métrique OpenTelemetry.

Attention: Les types d’agrégation au-delà de ce qui est indiqué dans la table 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 { ObservableResult, metrics } from "@opentelemetry/api";

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

let histogram = meter.createHistogram("histogram");
let counter = meter.createCounter("counter");
let gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
    let 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" });

Ajoutez des exceptions personnalisées

Sélectionnez des bibliothèques d’instrumentation qui prennent automatiquement en charge les exceptions à Application Insights. Toutefois, vous pouvez signaler manuellement des exceptions au-delà de ce que les bibliothèques d’instrumention rapportent. Par instance, 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 celles-ci dans les expériences pertinentes, y compris le panneau d’échecs et la vue transaction de bout en bout.

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

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

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

Dépannage

Autodiagnostics

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

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

process.env.APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL = "VERBOSE";
process.env.APPLICATIONINSIGHTS_LOG_DESTINATION = "file";
process.env.APPLICATIONINSIGHTS_LOGDIR = "C:/applicationinsights/logs";

useAzureMonitor();

APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVELla variable d’environnement peut être utilisée pour définir le niveau de journal souhaité, en prenant en charge les valeurs suivantes : NONE, ERROR, WARNINFO, , DEBUGVERBOSE et ALL.

Les journaux peuvent être placés dans un fichier local à l’aide APPLICATIONINSIGHTS_LOG_DESTINATION d’une variable d’environnement, les valeurs prises en charge sont file et file+console, un fichier nommé applicationinsights.log sera généré sur le dossier tmp par défaut, y compris tous les journaux, /tmp pour *nix et USERDIR/AppData/Local/Temp pour Windows. Le répertoire du journal 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 de plug-ins

Pour voir si un plug-in a déjà été créé pour une bibliothèque que vous utilisez, case activée le registre OpenTelemetry.

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

Contribution

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.