Share via

Azure Monitor OpenTelemetry für JavaScript

  • Artikel

NPM-Version

Erste Schritte

Installieren des Pakets

npm install @azure/monitor-opentelemetry

Die derzeitig unterstützten Umgebungen

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

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Aktivieren des Azure Monitor OpenTelemetry-Clients

Wichtig:useAzureMonitor muss aufgerufen werden, bevor Sie etwas anderes importieren. Es kann zu Telemetrieverlusten 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);
  • Die Verbindungszeichenfolge kann mithilfe der Umgebungsvariablen festgelegt werden, APPLICATIONINSIGHTS_CONNECTION_STRING

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);
Eigenschaft BESCHREIBUNG Standard
azureMonitorExporterOptions Azure Monitor OpenTelemetry Exporter-Konfiguration. Weitere Informationen finden Sie hier.
samplingRatio Das Stichprobenverhältnis muss einen Wert im Bereich [0,1], 1 annehmen, d. h. alle Daten werden abgetastet und 0 alle Ablaufverfolgungsdaten werden aus dem Stichprobenverfahren entnommen. 1
instrumentationOptions Zulassen der Konfiguration von OpenTelemetry-Instrumentierungen. {"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 Lässt die Konfiguration von Webinstrumentation zu. { enabled: false, connectionString: "" }
resource Opentelemetry-Ressource. Weitere Informationen finden Sie hier.
samplingRatio Das Stichprobenverhältnis muss einen Wert im Bereich [0,1], 1 annehmen, d. h. alle Daten werden abgetastet und 0 alle Ablaufverfolgungsdaten werden aus dem Stichprobenverfahren entnommen. 1
enableLiveMetrics Aktivieren/Deaktivieren von Livemetriken. false
enableStandardMetrics Aktivieren/Deaktivieren von Standardmetriken. true
logRecordProcessors Array von Protokolldatensatzprozessoren, die beim globalen Protokollierungsanbieter registriert werden sollen.
spanProcessors Array von span-Prozessoren, die beim globalen Ablaufverfolgungsanbieter registriert werden sollen.

Optionen können mithilfe der Konfigurationsdatei applicationinsights.json im Stammordner des Paketinstallationsordners @azure/monitor-opentelemetry festgelegt werden, 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
        }
    },
    ...
}

Eine benutzerdefinierte JSON-Datei kann mithilfe einer APPLICATIONINSIGHTS_CONFIGURATION_FILE Umgebungsvariable bereitgestellt werden.

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

// Application Insights SDK setup....

Instrumentierungsbibliotheken

Die folgenden OpenTelemetry-Instrumentierungsbibliotheken sind als Teil von Azure Monitor OpenTelemetry enthalten.

Warnung: Instrumentierungsbibliotheken basieren auf experimentellen OpenTelemetry-Spezifikationen. Die Vorschauunterstützung von Microsoft besteht darin, sicherzustellen, dass die unten aufgeführten Bibliotheken Daten an Azure Monitor Application Insights ausgeben, aber es ist möglich, dass Breaking Changes oder experimentelle Zuordnungen einige Datenelemente blockieren.

Verteilte Ablaufverfolgung

Metriken

Protokolle

Weitere OpenTelemetry-Instrumentierungen 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-Ladeprogramm

Mit dem Application Insights Browser SDK Loader können Sie das Web-SDK in Knotenserverantworten einfügen, wenn die folgenden Bedingungen erfüllt sind:

  • Die Antwort weist den Statuscode 200 auf.
  • Die Antwortmethode lautet GET.
  • Die Serverantwort weist den Conent-Type HTML-Header auf.
  • Serverresonse enthält sowohl tags als auch .
  • Die Antwort enthält keine aktuellen oder Sicherungs-CDN-Endpunkte für die Webinstrumentierung. (Aktuelle und Sicherungs-CDN-Endpunkte für die Webinstrumentierung finden Sie hier.)

Festlegen von Cloudrollennamen und Cloudrolleninstanz

Sie können den Cloudrollennamen und die Cloudrolleninstanz über OpenTelemetry-Ressourcenattribute 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.

Ändern der Telemetrie

In diesem Abschnitt wird das Ändern von Telemetriedaten erläutert.

Hinzufügen von span-Attributen

Verwenden Sie zum Hinzufügen von Span-Attributen eine der beiden folgenden Möglichkeiten:

Zu diesen Attributen kann das Hinzufügen einer benutzerdefinierten Eigenschaft zu Ihrer Telemetrie gehören.

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. Dadurch können Benutzer weitere Attribute hinzufügen oder filtern. Mit der Option „Anreichern“ in der HttpClient-Instrumentierungsbibliothek erhalten Benutzer beispielsweise Zugriff auf httpRequestMessage selbst. Sie können alles daraus auswählen und als Attribut speichern.

Hinzufügen einer benutzerdefinierten Eigenschaft zu einer Ablaufverfolgung

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

Verwenden eines benutzerdefinierten Prozessors:

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

Filtern von Telemetriedaten

Sie können die folgenden Methoden verwenden, um Telemetriedaten herausfiltern, bevor sie Ihre Anwendung verlassen.

  1. Option zum Ausschließen einer URL, die von vielen HTTP-Instrumentierungsbibliotheken bereitgestellt wird.

    Nachfolgend finden Sie ein Beispiel dafür, wie Sie eine bestimmte URL von der Nachverfolgung mithilfe der http/https-Instrumentierungsbibliothek ausschließen können:

    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 eines benutzerdefinierten Prozessors. Sie können einen benutzerdefinierten span-Prozessor verwenden, um bestimmte Spannen vom Export auszuschließen. Um Spannen zu markieren, die nicht exportiert werden sollen, legen Sie ihr TraceFlag auf DEFAULT fest. Verwenden Sie das Beispiel zum Hinzufügen einer benutzerdefinierten Eigenschaft, ersetzen Sie dabei aber die folgenden Codezeilen:

    ...
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 erfahren Sie, wie Sie benutzerdefinierte Telemetrie aus Ihrer Anwendung erfassen.

Hinzufügen benutzerdefinierter Metriken

Möglicherweise möchten Sie Metriken sammeln, die über die von Instrumentierungsbibliotheken gesammelten Metriken hinausgehen.

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

Die folgende Tabelle zeigt die empfohlenen Aggregationstypen] für jedes der OpenTelemetry-Metrikinstrumente.

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

Vorsicht: Aggregationstypen, die über das hinaus gehen, was in der Tabelle angezeigt wird, sind in der Regel nicht sinnvoll.

Die OpenTelemetry-Spezifikation beschreibt die Instrumente und enthält Verwendungsbeispiele.

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 benutzerdefinierter Ausnahmen

Bestimmte Instrumentierungsbibliotheken unterstützen automatisch Ausnahmen für Application Insights. Sie können jedoch Ausnahmen manuell melden, die über die Berichte von Instrumentierungsbibliotheken hinausgehen. Für instance werden ausnahmen, die von Ihrem Code erfasst werden, normalerweise nicht gemeldet, und Sie können sie melden und so in relevanten Erfahrungen, einschließlich des Fehlerblatts und der End-to-End-Transaktionsansicht, darauf aufmerksam machen.

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

Problembehandlung

Selbstdiagnose

Azure Monitor OpenTelemetry verwendet die OpenTelemetry-API-Protokollierung 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_LEVELUmgebungsvarialbe kann verwendet werden, um die gewünschte Protokollebene festzulegen, die die folgenden Werte unterstützt: NONE, ERROR, WARN, INFODEBUG, VERBOSE und ALL.

Protokolle können mithilfe der APPLICATIONINSIGHTS_LOG_DESTINATION Umgebungsvariablen in eine lokale Datei eingefügt werden. Unterstützte Werte sind 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 einer APPLICATIONINSIGHTS_LOGDIR Umgebungsvariablen konfiguriert werden.

Beispiele

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

Wichtige Begriffe

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

Plug-In-Registrierung

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

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

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe