Azure Monitor OpenTelemetry für JavaScript

Erste Schritte

Installieren des Pakets

npm install @azure/monitor-opentelemetry

Derzeit unterstützte Umgebungen

• LTS-Versionen von Node.js

• von OpenTelemetry unterstützte Laufzeiten

Warnung: Dieses SDK funktioniert nur für Node.js Umgebungen. Verwenden Sie das Application Insights JavaScript SDK- für Web- und Browserszenarien.

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Voraussetzungen

• Ein Azure-Abonnement
• Ein Application Insights-Arbeitsbereich

Aktivieren des Azure Monitor OpenTelemetry-Clients

Wichtig:useAzureMonitor muss aufgerufen werden, bevor Sie andere Elemente importieren. Es kann zu einem Telemetrieverlust kommen, wenn zuerst andere Bibliotheken importiert werden.

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

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

• Verbindungszeichenfolge kann mithilfe der Umgebungsvariablen APPLICATIONINSIGHTS_CONNECTION_STRING festgelegt werden.

Konfiguration

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

Eigentum	Beschreibung	Vorgabe
azureMonitorExporterOptions	Azure Monitor OpenTelemetry Exporter-Konfiguration. Weitere Informationen finden Sie hier
samplingRatio	Das Sampling-Verhältnis muss einen Wert im Bereich [0,1], 1 nehmen, was bedeutet, dass alle Daten abgesampt werden und 0 alle Ablaufverfolgungsdaten abgesampt werden.	1
instrumentationOptions	Konfiguration von OpenTelemetry Instrumentations zulassen.	{"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	Konfiguration von Webinstrumentation zulassen.	{ enabled: false, connectionString: "" }
Ressource	Opentelemetry-Ressource. Weitere Informationen finden Sie hier
samplingRatio	Das Sampling-Verhältnis muss einen Wert im Bereich [0,1], 1 nehmen, was bedeutet, dass alle Daten abgesampt werden und 0 alle Ablaufverfolgungsdaten abgesampt werden.	1
enableLiveMetrics	Livemetriken aktivieren/deaktivieren.	STIMMT
enableStandardMetrics	Standardmetriken aktivieren/deaktivieren.	STIMMT
logRecordProcessors	Array von Protokolldatensatzprozessoren, die beim globalen Loggeranbieter registriert werden sollen.
spanProcessors	Array von Span-Prozessoren, die beim globalen Ablaufverfolgungsanbieter registriert werden sollen.
enableTraceBasedSamplingForLogs	Aktivieren Sie das Protokollsampling basierend auf der Ablaufverfolgung.	FALSCH

Optionen können mithilfe der Konfigurationsdatei festgelegt werden, applicationinsights.json sich im Stammordner @azure/monitor-opentelemetry Paketinstallationsordners befindet, z. B. node_modules/@azure/monitor-opentelemetry. Diese Konfigurationswerte werden auf alle AzureMonitorOpenTelemetryClient-Instanzen angewendet.

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

Benutzerdefinierte JSON-Datei kann mithilfe APPLICATIONINSIGHTS_CONFIGURATION_FILE Umgebungsvariable bereitgestellt werden.

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

// Application Insights SDK setup....

Instrumentationsbibliotheken

Die folgenden OpenTelemetry Instrumentations-Bibliotheken sind bestandteil von Azure Monitor OpenTelemetry.

Warnung: Instrumentationsbibliotheken basieren auf experimentellen OpenTelemetry-Spezifikationen. Microsofts Vorschau- Supportverpflichtung besteht darin, sicherzustellen, dass die folgenden Bibliotheken Daten an Azure Monitor Application Insights ausgeben, aber es ist möglich, dass unterbrechungsgesteuerte Änderungen oder experimentelle Zuordnung einige Datenelemente blockieren.

Verteilte Ablaufverfolgung

• HTTP/HTTPS-
• MongoDB-
• MySQL
• Postgres
• Redis
• Redis-4-
• Azure SDK-

Metrik

• HTTP/HTTPS-

Baumstämme

• Bunyan

• Winston

Weitere OpenTelemetry Instrumentations sind hier verfügbar und können mithilfe von TracerProvider in AzureMonitorOpenTelemetryClient hinzugefügt werden.

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

Application Insights Browser SDK Loader

Application Insights Browser SDK Loader ermöglicht es Ihnen, das Web SDK in Knotenserverantworten einzufügen, wenn die folgenden Bedingungen zutreffen:

• Antwort hat Statuscode 200.
• Die Antwortmethode ist GET.
• Die Serverantwort verfügt über den html-Header Conent-Type.
• Server-Resonse enthält sowohl als auch Tags.
• Die Antwort enthält keine aktuellen /backup Web Instrumentation CDN-Endpunkte. (aktuelle und backup Web Instrumentation CDN-Endpunkte hier)

Weitere Informationen zur Verwendung des Browser-SDK-Ladeprogramm finden Sie hier.

Festlegen des Cloudrollennamens und der Cloudrolleninstanz

Sie können den Cloudrollennamen und die Cloudrolleninstanz über OpenTelemetry Resource Attribute festlegen.

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

Informationen zu Standardattributen für Ressourcen finden Sie unter Ressourcensemantikkonventionen.

Telemetrie ändern

In diesem Abschnitt wird erläutert, wie Telemetrie geändert wird.

Hinzufügen von Span-Attributen

Verwenden Sie zum Hinzufügen von Span-Attributen eine der folgenden beiden Methoden:

• Verwenden Sie Optionen, die von Instrumentationsbibliothekenbereitgestellt werden.
• Fügen Sie einen benutzerdefinierten Span-Prozessor hinzu.

Diese Attribute können das Hinzufügen einer benutzerdefinierten Eigenschaft zu Ihrer Telemetrie umfassen.

Tipp: Der Vorteil der Verwendung von Optionen, die von Instrumentierungsbibliotheken bereitgestellt werden, wenn sie verfügbar sind, besteht darin, dass der gesamte Kontext verfügbar ist. Daher können Benutzer auswählen, um weitere Attribute hinzuzufügen oder zu filtern. Beispielsweise ermöglicht die Erweiterungsoption in der HttpClient-Instrumentierungsbibliothek Benutzern zugriff auf die httpRequestMessage selbst. Sie können alles auswählen und als Attribut speichern.

Hinzufügen einer benutzerdefinierten Eigenschaft zu einer Ablaufverfolgung

Alle Attribute, die Sie zu Spans hinzufügen, werden als benutzerdefinierte Eigenschaften exportiert.

Verwenden Sie einen benutzerdefinierten Prozessor:

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

Vorgangsname zu Ablaufverfolgungen und Protokollen hinzufügen

Verwenden Sie einen benutzerdefinierten Prozessor- und Protokolldatensatzprozessor, um den Vorgangsnamen von Anforderungen an Abhängigkeiten und Protokolle anzufügen und zu korrelieren.

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

class SpanEnrichingProcessor implements SpanProcessor {
  forceFlush(): Promise<void> {
    return Promise.resolve();
  }
  shutdown(): Promise<void> {
    return Promise.resolve();
  }
  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.attributes[AI_OPERATION_NAME] = (parentSpan as unknown as ReadableSpan).name;
    }
  }
  onEnd(span: ReadableSpan) {}
}

class LogRecordEnrichingProcessor implements LogRecordProcessor {
  forceFlush(): Promise<void> {
    return Promise.resolve();
  }
  shutdown(): Promise<void> {
    return Promise.resolve();
  }
  onEmit(_logRecord, _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.attributes[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);

Filtern von Telemetrie

Sie können die folgenden Möglichkeiten verwenden, um Telemetrie herauszufiltern, bevor sie Ihre Anwendung verlässt.

1. Schließen Sie die URL-Option aus, die von vielen HTTP-Instrumentationsbibliotheken bereitgestellt wird.

   Das folgende Beispiel zeigt, wie Sie mithilfe der HTTP/HTTPS-Instrumentierungsbibliothekeine bestimmte URL von der Nachverfolgung ausschließen:

   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. Verwenden Sie einen benutzerdefinierten Prozessor. Sie können einen benutzerdefinierten Span-Prozessor verwenden, um bestimmte Spans vom Export auszuschließen. Legen Sie TraceFlag auf DEFAULTfest, um die Spannweiten zu markieren, die nicht exportiert werden sollen. Verwenden Sie das Add-benutzerdefinierte Eigenschaftsbeispiel, ersetzen Sie jedoch die folgenden Codezeilen:

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

Benutzerdefinierte Telemetrie

In diesem Abschnitt wird erläutert, wie Sie benutzerdefinierte Telemetrie aus Ihrer Anwendung sammeln.

Hinzufügen von benutzerdefinierten Metriken

Möglicherweise möchten Sie Metriken über das sammeln, was von Instrumentationsbibliothekengesammelt wird.

Die OpenTelemetry-API bietet sechs Metriken "Instrumente", um eine Vielzahl von Metrikszenarien abzudecken, und Sie müssen beim Visualisieren von Metriken im Metrik-Explorer den richtigen "Aggregationstyp" auswählen. Diese Anforderung gilt bei Verwendung der OpenTelemetry Metric-API zum Senden von Metriken und bei Verwendung einer Instrumentierungsbibliothek.

In der folgenden Tabelle sind die empfohlenen Aggregationstypen für jedes der OpenTelemetry Metric Instruments aufgeführt.

OpenTelemetry-Instrument	Azure Monitor Aggregationstyp
Zähler	Summe
Asynchroner Zähler	Summe
Histogramm	Mittelwert, Summe, Anzahl (Max, Min für Python und Node.js nur)
Asynchrones Messgeräte	Durchschnitt
UpDownCounter (nur Python und Node.js)	Summe
Asynchrones UpDownCounter (nur Python und Node.js)	Summe

Vorsicht: Aggregationstypen, die über die in der Tabelle dargestellten Elemente hinausgehen, sind in der Regel nicht aussagekräftig.

Die OpenTelemetry Specification beschreibt die Instrumente und enthält Beispiele für die Verwendung der einzelnen Instrumente.

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

Hinzufügen von benutzerdefinierten Ausnahmen

Wählen Sie Instrumentationsbibliotheken aus, die Ausnahmen von Application Insights automatisch unterstützen. Sie können jedoch Ausnahmen manuell melden, die über den Bericht der Instrumentierungsbibliotheken hinausgehen. Ausnahmen, die von Ihrem Code erfasst werden, werden beispielsweise nicht nicht gemeldet, und Sie können sie melden und sie daher in relevanten Erfahrungen, einschließlich des Fehlerblatts und der End-to-End-Transaktionsansicht, auf sie aufmerksam machen.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { trace, Exception } 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 as Exception);
}

Fehlerbehebung

Selbstdiagnose

Azure Monitor OpenTelemetry verwendet den OpenTelemetry-API-Logger für interne Protokolle. Verwenden Sie zum Aktivieren den folgenden Code:

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_LEVEL Umgebungsvariable kann zum Festlegen der gewünschten Protokollebene verwendet werden, wobei die folgenden Werte unterstützt werden: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE und ALL.

Protokolle können mithilfe APPLICATIONINSIGHTS_LOG_DESTINATION Umgebungsvariablen in eine lokale Datei eingefügt werden, unterstützte Werte werden file und file+console, eine Datei mit dem Namen applicationinsights.log wird standardmäßig im TMP-Ordner generiert, einschließlich aller Protokolle, /tmp für *nix und USERDIR/AppData/Local/Temp für Windows. Das Protokollverzeichnis kann mithilfe APPLICATIONINSIGHTS_LOGDIR Umgebungsvariablen konfiguriert werden.

Beispiele

Vollständige Beispiele für einige Champion-Szenarien finden Sie im Ordner "samples/".

Schlüsselkonzepte

Weitere Informationen zum OpenTelemetry-Projekt finden Sie in den OpenTelemetry Specifications.

Plug-In-Registrierung

Um festzustellen, ob ein Plug-In bereits für eine bibliothek erstellt wurde, die Sie verwenden, lesen Sie bitte die OpenTelemetry Registry.

Wenn Sie Ihre Bibliothek in der Registrierung nicht verwenden können, können Sie unter opentelemetry-js-contribeine neue Plug-In-Anforderung vorschlagen.

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.