OpenTelemetry di Monitoraggio di Azure per JavaScript

Articolo
05/10/2024

Introduzione

Installare il pacchetto

npm install @azure/monitor-opentelemetry

Ambienti attualmente supportati

Avviso: Questo SDK funziona solo per gli ambienti Node.js. Usare Application Insights JavaScript SDK per scenari web e browser.

Per altre informazioni, vedere i criteri di supporto.

Prerequisiti

Abilitare il client OpenTelemetry di Monitoraggio di Azure

Importante:useAzureMonitor deve essere chiamato prima di importare qualcos'altro. Se altre librerie vengono importate per prime, potrebbero verificarsi perdite di dati di telemetria.

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

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

La stringa di connessione può essere impostata usando la variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING

Configurazione

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

Proprietà	Descrizione	Predefinito
azureMonitorExporterOptions	Configurazione dell'utilità di esportazione OpenTelemetry di Monitoraggio di Azure. Altre informazioni qui
samplingRatio	Il rapporto di campionamento deve accettare un valore nell'intervallo [0,1], ovvero tutti i dati verranno campionati e verranno campionati tutti i dati di traccia.	1
instrumentationOptions	Consenti la configurazione di Strumentazioni OpenTelemetry.	{"http": { enabled: true },"azureSdk": { enabled: false },"mongoDb": { enabled: false },"mySql": { enabled: false },"postgreSql": { enabled: false },"redis": { enabled: false },"bunyan": { enabled: false }, "winston": { enabled: false } }
browserSdkLoaderOptions	Consenti la configurazione di Strumentazioni Web.	{ enabled: false, connectionString: "" }
Risorsa	Risorsa Opentelemetry. Altre informazioni qui
samplingRatio	Il rapporto di campionamento deve accettare un valore nell'intervallo [0,1], ovvero tutti i dati verranno campionati e verranno campionati tutti i dati di traccia.	1
enableLiveMetrics	Abilitare/disabilitare le metriche attive.	false
enableStandardMetrics	Abilitare/disabilitare le metriche standard.	true
logRecordProcessors	Matrice di processori di record di log da registrare nel provider di logger globale.
spanProcessor	Matrice di processori span da registrare nel provider di traccia globale.

Le opzioni possono essere impostate usando il file applicationinsights.json di configurazione che si trova nella cartella radice della cartella di installazione del @azure/monitor-opentelemetry pacchetto, ad esempio node_modules/@azure/monitor-opentelemetry. Questi valori di configurazione verranno applicati a tutte le istanze di AzureMonitorOpenTelemetryClient.

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

È possibile specificare un file JSON personalizzato usando APPLICATIONINSIGHTS_CONFIGURATION_FILE la variabile di ambiente.

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

// Application Insights SDK setup....

Librerie di strumentazione

Le librerie di strumentazione OpenTelemetry seguenti sono incluse come parte di OpenTelemetry di Monitoraggio di Azure.

Avviso: Le librerie di strumentazione si basano sulle specifiche sperimentali di OpenTelemetry. L'impegno di supporto per l'anteprima di Microsoft consiste nel garantire che le librerie seguenti emettano dati in Application Insights di Monitoraggio di Azure, ma è possibile che le modifiche di rilievo o il mapping sperimentale blocchino alcuni elementi dati.

Traccia distribuita

Metriche

HTTP/HTTPS

Log

Altre strumentazioni OpenTelemetry sono disponibili qui e possono essere aggiunte usando TracerProvider in 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,
});

Caricatore di Application Insights Browser SDK

Application Insights Browser SDK Loader consente di inserire l'SDK Web nelle risposte del server node quando si verificano le condizioni seguenti:

La risposta ha il codice 200di stato .
Il metodo di risposta è GET.
La risposta del server ha l'intestazione Conent-Type HTML.
Il resonse del server contiene sia tag che .
La risposta non contiene gli endpoint della rete CDN di Strumentazione Web /backup correnti. (gli endpoint della rete CDN di Strumentazione Web corrente e di backup sono disponibili qui)

Impostare il nome del ruolo cloud e l'istanza del ruolo cloud

È possibile impostare il nome del ruolo cloud e l'istanza del ruolo cloud tramite gli attributi della risorsa 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);

Per informazioni sugli attributi standard per le risorse, vedere Convenzioni semantiche delle risorse.

Modificare la telemetria

Questa sezione illustra come modificare i dati di telemetria.

Aggiungere attributi span

Per aggiungere attributi span, usare uno dei due modi seguenti:

Usare le opzioni fornite dalle librerie di strumentazione.
Aggiungere un processore di intervallo personalizzato.

Questi attributi possono includere l'aggiunta di una proprietà personalizzata ai dati di telemetria.

Mancia: Il vantaggio dell'uso delle opzioni offerte dalle librerie di strumentazione, quando disponibili, è che l'intero contesto è disponibile. Di conseguenza, gli utenti possono scegliere di aggiungere o filtrare più attributi. Ad esempio, l'opzione di arricchimento nella libreria di strumentazione HttpClient consente agli utenti di accedere a httpRequestMessage stesso. Possono selezionare qualsiasi elemento da esso e archiviarlo come attributo.

Aggiungere una proprietà personalizzata a una traccia

Tutti gli attributi aggiunti agli intervalli vengono esportati come proprietà personalizzate.

Usare un processore personalizzato:

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

Filtrare i dati di telemetria

È possibile usare i modi seguenti per filtrare i dati di telemetria prima di uscire dall'applicazione.

Escludere l'opzione URL fornita da molte librerie di strumentazione HTTP.

Nell'esempio seguente viene illustrato come escludere un determinato URL da tenere traccia usando la libreria di strumentazione 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);

Usare un processore personalizzato. È possibile usare un processore di intervallo personalizzato per escludere determinati intervalli da esportare. Per contrassegnare gli intervalli da esportare, impostare TraceFlag su DEFAULT. Usare l'esempio di proprietà personalizzata, ma sostituire le righe di codice seguenti:

...
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;
        }
    }
}

Telemetria personalizzata

Questa sezione illustra come raccogliere dati di telemetria personalizzati dall'applicazione.

Aggiungere metriche personalizzate

È possibile raccogliere metriche oltre a ciò che viene raccolto dalle librerie di strumentazione.

L'API OpenTelemetry offre sei metriche "instrument" per coprire diversi scenari di metrica e sarà necessario selezionare il tipo di aggregazione corretto quando si visualizzano le metriche in Esplora metriche. Questo requisito è true quando si usa l'API Metrica OpenTelemetry per inviare metriche e quando si usa una libreria di strumentazione.

Nella tabella seguente vengono illustrati i tipi di aggregazione consigliati per ognuno degli strumenti di metrica OpenTelemetry.

OpenTelemetry Instrument	Tipo di aggregazione di Monitoraggio di Azure
Contatore	Sum
Contatore asincrono	Sum
Istogramma	Media, Somma, Conteggio (Max, Min per Python e solo Node.js)
Misuratore asincrono	Media
UpDownCounter (solo Python e Node.js)	Sum
UpDownCounter asincrono (solo Python e Node.js)	Sum

Attenzione: I tipi di aggregazione oltre a quelli visualizzati nella tabella in genere non sono significativi.

La specifica OpenTelemetry descrive gli strumenti e fornisce esempi di quando è possibile usare ognuno di essi.

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

Aggiungere eccezioni personalizzate

Selezionare le librerie di strumentazione supportano automaticamente le eccezioni in Application Insights. Tuttavia, è possibile segnalare manualmente eccezioni oltre a ciò che segnalano le librerie di strumenti. Ad esempio, le eccezioni rilevate dal codice non sono normalmente segnalate e potrebbero essere necessarie per segnalarle e quindi attirare l'attenzione su di esse in esperienze pertinenti, tra cui il pannello degli errori e la visualizzazione delle transazioni end-to-end.

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

Risoluzione dei problemi

Diagnostica automatica

Monitoraggio di Azure OpenTelemetry usa l'API OpenTelemetry Logger per i log interni. Per abilitarlo, usare il codice seguente:

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_LEVELl'ambiente varialbe può essere usato per impostare il livello di log desiderato, supportando i valori seguenti: NONEINFOWARNDEBUGERRORVERBOSE , e .ALL

I log possono essere inseriti nel file locale usando APPLICATIONINSIGHTS_LOG_DESTINATION la variabile di ambiente, i valori supportati sono file e file+console, un file denominato applicationinsights.log verrà generato nella cartella tmp per impostazione predefinita, inclusi tutti i log, /tmp per *nix e USERDIR/AppData/Local/Temp per Windows. La directory di log può essere configurata usando APPLICATIONINSIGHTS_LOGDIR la variabile di ambiente.

Esempio

Per esempi completi di alcuni scenari campione, vedere la samples/ cartella.

Concetti chiave

Per altre informazioni sul progetto OpenTelemetry, vedere Le specifiche openTelemetry.

Registro plug-in

Per verificare se è già stato creato un plug-in per una libreria in uso, consultare il Registro di sistema OpenTelemetry.

Se non è possibile visualizzare la libreria nel Registro di sistema, è possibile suggerire una nuova richiesta di plug-in all'indirizzo opentelemetry-js-contrib.

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.

Impression

Condividi tramite