Freigeben über

Azure Monitor OpenTelemetry für JavaScript

NPM-Version

Erste Schritte

Installiere das Paket

npm install @azure/monitor-opentelemetry

Derzeit unterstützte Umgebungen

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

Aktivieren des Azure Monitor OpenTelemetry-Clients

Wichtig:useAzureMonitor muss aufgerufen werden , bevor Sie etwas anderes importieren. Es kann zu Telemetrieverlusten kommen, wenn andere Bibliotheken zuerst importiert werden.

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

const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString:
      process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
  },
};
useAzureMonitor(options);
  • Connection String kann mit der Umgebungsvariablen APPLICATIONINSIGHTS_CONNECTION_STRINGfestgelegt werden.

Konfiguration

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);
Auswahlmöglichkeit BESCHREIBUNG Standard
azureMonitorExporterOptions Konfiguration des Azure Monitor-OpenTelemetry-Exporters. Mehr Infos hier
samplingRatio Das Stichprobenverhältnis muss einen Wert im Bereich [0,1], 1 annehmen, was bedeutet, dass alle Daten abgetastet werden, und 0, alle Ablaufverfolgungsdaten werden abgetastet. 1
instrumentationOptions Konfiguration der Instrumentationsbibliotheken. Mehr Infos hier 

{
  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 Konfiguration von Webinstrumentationen zulassen. 
        
{ 
  enabled: false, 
  connectionString: "" 
}
resource Opentelemetrie-Ressource. Mehr Infos hier
enableLiveMetrics Aktivieren/Deaktivieren von Live-Metriken. true
enableStandardMetrics Aktivieren/Deaktivieren von Standardmetriken. true
logRecordProcessors Array von Protokolldatensatzprozessoren für die Registrierung beim globalen Protokollierungsanbieter.
spanProcessors Array von Span-Prozessoren, die beim globalen Überwachungsanbieter registriert werden sollen.
enableTraceBasedSamplingForLogs Aktivieren Sie die Protokollstichprobenerstellung basierend auf der Ablaufverfolgung. false
enablePerformanceCounters Aktivieren Sie Leistungsindikatoren. true

Die Optionen können mithilfe der Konfigurationsdatei applicationinsights.json festgelegt werden, die sich im Stammordner des Paketinstallationsordners @azure/monitor-opentelemetry befindet, z. node_modules/@azure/monitor-opentelemetryB.: . 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 der APPLICATIONINSIGHTS_CONFIGURATION_FILE Umgebungsvariablen bereitgestellt werden.

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

Instrumentierungsbibliotheken

Die folgenden OpenTelemetry-Instrumentationsbibliotheken sind Teil von Azure Monitor OpenTelemetry.

Anmerkung: Die Azure SDK-, MongoDB-, MySQL-, PostgreSQL-, Redis- und Redis-4-Instrumentationen sind standardmäßig für die verteilte Ablaufverfolgung aktiviert. Die HTTP/HTTPS-Instrumentierung ist ebenfalls standardmäßig aktiviert. Alle anderen Instrumentierungen sind standardmäßig deaktiviert und können durch Festlegen enabled: true in den Instrumentierungsoptionen aktiviert werden.

Warnung: Instrumentierungsbibliotheken basieren auf experimentellen OpenTelemetry-Spezifikationen. Die Verpflichtung von Microsoft zum Preview-Support besteht darin, sicherzustellen, dass die folgenden 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

Logdateien

Andere OpenTelemetry-Instrumentationen sind hier verfügbar und können mithilfe von TracerProvider in AzureMonitorOpenTelemetryClient hinzugefügt werden.

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-Ladeprogramm

Mit dem Application Insights-Browser-SDK-Ladeprogramm 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 hat den Conent-Type HTML-Header.
  • Server resonse enthält sowohl die Tags als auch die Tags.
  • Die Antwort enthält keine aktuellen oder Sicherungs-CDN-Endpunkte für die Webinstrumentierung. (Aktuelle und Backup-Endpunkte des Web-Instrumentierungs-CDN finden Sie hier.)

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

Festlegen von Cloudrollennamen und Cloudrolleninstanz

Sie können den Cloud-Rollennamen und die Cloud-Rolleninstanz über die OpenTelemetry-Ressourcenattribute festlegen.

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

Weitere Informationen zu Standardattributen für Ressourcen finden Sie unter Semantische Konventionen für Ressourcen.

Ä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.

Trinkgeld: Der Vorteil der Verwendung von Optionen, die von Instrumentenbibliotheken bereitgestellt werden, besteht darin, dass der gesamte Kontext verfügbar ist, sofern sie verfügbar sind. 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 { 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);

Hinzufügen eines Vorgangsnamens zu Ablaufverfolgungen und Protokollen

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

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

Filtern von Telemetrie

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

  1. Schließen Sie die URL-Option aus, 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 { 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. Verwenden Sie einen benutzerdefinierten Prozessor. 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, aber ersetzen Sie die folgenden Codezeilen:

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

Benutzerdefinierte Telemetrie

In diesem Abschnitt erfahren Sie, wie Sie benutzerdefinierte Telemetrie aus Ihrer Anwendung erfassen.

Hinzufügen von benutzerdefinierten Metriken

Möglicherweise möchten Sie Metriken sammeln, die über das hinausgehen, was von Instrumentierungsbibliotheken erfasst wird.

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

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

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

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

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

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

Hinzufügen von benutzerdefinierten Ausnahmen

Ausgewählte Instrumentationsbibliotheken unterstützen automatisch Ausnahmen für Application Insights. Es kann jedoch sinnvoll sein, Ausnahmen manuell zu melden, die über das hinausgehen, was Instrumentierungsbibliotheken melden. Beispielsweise werden Ausnahmen, die von Ihrem Code abgefangen werden, normalerweise nicht gemeldet, und Sie möchten sie möglicherweise 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, 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);
}

Problembehandlung

Selbstdiagnose

Azure Monitor OpenTelemetry verwendet die OpenTelemetry-API-Protokollierung für interne Protokolle. Verwenden Sie den folgenden Code, um ihn zu aktivieren:

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_LEVELDie Umgebungsvariable kann verwendet werden, um die gewünschte Protokollebene festzulegen, die die folgenden Werte unterstützt: NONE, ERROR, WARN, INFO, DEBUGVERBOSE und ALL.

Protokolle können mit der APPLICATIONINSIGHTS_LOG_DESTINATION Umgebungsvariablen in eine lokale Datei gelegt werden, unterstützte Werte sind file und , file+consoleeine 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 der APPLICATIONINSIGHTS_LOGDIR Umgebungsvariablen konfiguriert werden.

Beispiele

Vollständige Beispiele einiger Champion-Szenarien finden Sie in diesem samples/ Ordner.

Wichtige Begriffe

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

Plugin-Registrierung

Um zu sehen, ob bereits ein Plugin für eine von Ihnen verwendete Bibliothek erstellt wurde, schauen Sie bitte in der OpenTelemetry Registry nach.

Wenn Sie Ihre Bibliothek nicht in der Registry finden können, können Sie gerne eine neue Plugin-Anfrage unter opentelemetry-js-contribvorschlagen.

Mitarbeit

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.

  • Last updated on