Condividi tramite

Monitoraggio di Azure OpenTelemetry per JavaScript

Versione npm

Come iniziare

Installare il pacchetto

npm install @azure/monitor-opentelemetry

Ambienti attualmente supportati

Avvertimento: Questo SDK funziona solo per ambienti Node.js. Usare Application Insights JavaScript SDK per scenari Web e browser.

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

Abilitare il client OpenTelemetry di Monitoraggio di Azure

Importante:useAzureMonitor deve essere chiamato prima di importare qualsiasi altra cosa. Se altre librerie vengono importate per prime, potrebbe verificarsi una perdita di dati di telemetria.

import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } 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 utilizzando la variabile APPLICATIONINSIGHTS_CONNECTION_STRINGd'ambiente .

Configurazione

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);
Opzione Descrizione Predefinito
azureMonitorExporterOptions Configurazione dell'utilità di esportazione OpenTelemetry di Monitoraggio di Azure. Maggiori informazioni qui
samplingRatio Il rapporto di campionamento deve assumere un valore compreso nell'intervallo [0,1], il che significa che tutti i dati verranno campionati e 0 tutti i dati di tracciamento verranno campionati. 1
instrumentationOptions Configurazione delle librerie di strumentazione. Maggiori informazioni qui 

{
  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 Consenti la configurazione delle strumentazioni Web. 
        
{ 
  enabled: false, 
  connectionString: "" 
}
resource Risorsa Opentelemetry. Maggiori informazioni qui
enableLiveMetrics Abilita/disabilita le metriche in tempo reale. true
enableStandardMetrics Abilita/disabilita le metriche standard. true
logRecordProcessors Matrice di processori di record di log da registrare nel provider di logger globale.
spanProcessors Matrice di processori span da registrare nel provider di traccia globale.
enableTraceBasedSamplingForLogs Abilitare il campionamento dei log in base alla traccia. false
enablePerformanceCounters Abilitare i contatori delle prestazioni. true

Le opzioni possono essere impostate utilizzando il file applicationinsights.json di configurazione che si trova nella cartella principale 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
        }
    },
    ...
}

Il file JSON personalizzato può essere fornito utilizzando la APPLICATIONINSIGHTS_CONFIGURATION_FILE variabile di ambiente.

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

Librerie di strumentazione

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

Nota: Le strumentazioni Azure SDK, MongoDB, MySQL, PostgreSQL, Redis e Redis-4 sono abilitate per impostazione predefinita per la traccia distribuita. Anche la strumentazione HTTP/HTTPS è abilitata per impostazione predefinita. Tutte le altre strumentazioni sono disabilitate per impostazione predefinita e possono essere abilitate impostando enabled: true nelle opzioni di strumentazione.

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

Tracciamento distribuito

Metriche

Registrazioni

Altre strumentazioni OpenTelemetry sono disponibili qui e possono essere aggiunte usando TracerProvider in 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 consente di inserire l'SDK Web nelle risposte del server del nodo quando si verificano le condizioni seguenti:

  • La risposta ha il codice di stato 200.
  • Il metodo di risposta è GET.
  • La risposta del server ha l'intestazione Conent-Type html.
  • Server resonse contiene sia i tag and.
  • La risposta non contiene gli endpoint correnti/di backup della rete CDN della strumentazione Web. (endpoint correnti e di backup della rete CDN della strumentazione Web qui)

Ulteriori informazioni sull'utilizzo del caricatore SDK del browser sono disponibili qui.

Impostare il nome 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 { 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);

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 di span, usare uno dei seguenti due modi:

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

Mancia: Il vantaggio di utilizzare le opzioni fornite dalle librerie di strumentazione, quando sono disponibili, è che l'intero contesto è disponibile. Di conseguenza, gli utenti possono effettuare una selezione per aggiungere o filtrare altri attributi. Ad esempio, l'opzione enrich nella libreria di strumentazione HttpClient consente agli utenti di accedere allo stesso HttpRequestMessage. Da lì, possono selezionare qualsiasi elemento e archiviarlo come attributo.

Aggiungere una proprietà personalizzata a un oggetto Trace

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

Usare un processore personalizzato:

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

Aggiunta del nome dell'operazione a tracce e registri

Utilizzare un processore di estensione personalizzato e un elaboratore di record di log per collegare e correlare il nome dell'operazione dalle richieste alle dipendenze e ai log.

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

Filtrare i dati di telemetria

È possibile usare i modi seguenti per filtrare i dati di telemetria prima che lascino l'applicazione.

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

    L'esempio seguente illustra come escludere un determinato URL dal rilevamento usando la libreria di strumentazione 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);

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

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

Telemetria personalizzata

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

Aggiungi metriche personalizzate

È possibile raccogliere metriche oltre a quelle raccolte dalle librerie di strumentazione.

L'API OpenTelemetry offre sei "strumenti" di metrica per coprire un'ampia gamma di scenari di metriche e sarà necessario selezionare il "tipo di aggregazione" corretto quando si visualizzano le metriche in Esplora metriche. Questo requisito è vero 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 metrici OpenTelemetry.

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

Cautela: I tipi di aggregazione oltre a quelli mostrati 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 { 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" });

Aggiunta di eccezioni personalizzate

Le librerie di strumentazione selezionate supportano automaticamente le eccezioni ad Application Insights. Tuttavia, è possibile segnalare manualmente le eccezioni oltre a quelle segnalate dalle librerie di strumentazione. Ad esempio, le eccezioni rilevate dal codice non vengono in genere non segnalate e potrebbe essere necessario segnalarle e quindi attirare l'attenzione su di esse nelle esperienze pertinenti, tra cui il pannello degli errori e la visualizzazione delle transazioni end-to-end.

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

Risoluzione dei problemi

Diagnostica self-service

Monitoraggio di Azure OpenTelemetry usa il logger API OpenTelemetry per i log interni. Per abilitarlo, utilizzare il codice seguente:

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_LEVEL La variabile d'ambiente può essere utilizzata per impostare il livello di log desiderato, supportando i seguenti valori: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE e ALL.

I log possono essere inseriti in un file locale utilizzando APPLICATIONINSIGHTS_LOG_DESTINATION la variabile d'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 utilizzando la APPLICATIONINSIGHTS_LOGDIR variabile d'ambiente.

Esempi

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

Concetti chiave

Per altre informazioni sul progetto OpenTelemetry, vedere le specifiche OpenTelemetry.

Registro dei plugin

Per vedere se è già stato creato un plug-in per una libreria che stai utilizzando, consulta il registro OpenTelemetry.

Se non riesci a inserire la tua libreria nel registro, sentiti libero di suggerire una nuova richiesta di plug-in all'indirizzo opentelemetry-js-contrib.

Contribuire

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

  • Last updated on