Azure Monitor OpenTelemetry Exporter client library for JavaScript - version 1.0.0-beta.45

NPM-Version

Erste Schritte

Bei diesem Exportpaket wird davon ausgegangen, dass Ihre Anwendung bereits mit dem OpenTelemetry SDK instrumentiert ist . Sobald Sie bereit sind, OpenTelemetry-Daten zu exportieren, können Sie diesen Exporter zu Ihrer Anwendung hinzufügen.

Installiere das Paket

npm install @azure/monitor-opentelemetry-exporter

Derzeit unterstützte Umgebungen

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Warnung: Dieses SDK funktioniert nur für Node.js Umgebungen. Verwenden Sie das Application Insights JavaScript SDK für Browserumgebungen.

Voraussetzungen

Verteilte Ablaufverfolgung

Fügen Sie den Exporter zu Ihrem vorhandenen OpenTelemetry-Tracer-Anbieter hinzu (NodeTracerProvider / BasicTracerProvider)

import { AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter";
import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

// Create an exporter instance
const exporter = new AzureMonitorTraceExporter({
  connectionString: "<connection string>",
});

// Create and configure the Node Tracer provider
const tracerProvider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: "basic-service",
  }),
  spanProcessors: [
    new BatchSpanProcessor(exporter, {
      exportTimeoutMillis: 15000,
      maxQueueSize: 1000,
    }),
  ],
});

// Register Tracer Provider as global
tracerProvider.register();

Metriken

Hinzufügen des Exportprogramms zu Ihrem vorhandenen OpenTelemetry Meter Provider (MeterProvider)

import { AzureMonitorMetricExporter } from "@azure/monitor-opentelemetry-exporter";
import { PeriodicExportingMetricReader, MeterProvider } from "@opentelemetry/sdk-metrics";
import { metrics } from "@opentelemetry/api";

// Add the exporter into the MetricReader and register it with the MeterProvider
const exporter = new AzureMonitorMetricExporter({
  connectionString: "<connection string>",
});

const metricReaderOptions = {
  exporter: exporter,
};
const metricReader = new PeriodicExportingMetricReader(metricReaderOptions);
const meterProvider = new MeterProvider({
  readers: [metricReader],
});

// Register Meter Provider as global
metrics.setGlobalMeterProvider(meterProvider);

Logdateien

Hinzufügen des Protokollexportprogramms zu Ihrem vorhandenen OpenTelemetry Logger-Anbieter (LoggerProvider)

import { AzureMonitorLogExporter } from "@azure/monitor-opentelemetry-exporter";
import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
import { logs } from "@opentelemetry/api-logs";

// Add the Log exporter into the logRecordProcessor and register it with the LoggerProvider
const exporter = new AzureMonitorLogExporter({
  connectionString: "<connection string>",
});

const logRecordProcessor = new BatchLogRecordProcessor({ exporter });
const loggerProvider = new LoggerProvider({
  processors: [logRecordProcessor],
});

// Register logger Provider as global
logs.setGlobalLoggerProvider(loggerProvider);

Verfügbarkeitsergebnisse

Nach der Registrierung des Logger-Anbieters senden Sie einen OpenTelemetrie-Protokoll mit den unten aufgeführten Verfügbarkeitsattributen. Der Exporteur wandelt den Datensatz in Application Insights Verfügbarkeitstelemetrie um.

import { logs } from "@opentelemetry/api-logs";

const logger = logs.getLogger("availability");
logger.emit({
  body: "Homepage availability test completed.",
  attributes: {
    "microsoft.availability.id": "availability-test-run-123",
    "microsoft.availability.name": "Homepage",
    "microsoft.availability.duration": "00:00:00.250",
    "microsoft.availability.success": true,
    "microsoft.availability.runLocation": "westus2",
    "microsoft.availability.message": "HTTP 200",
  },
});

Die folgenden Attribute sind erforderlich:

Attribute Description
microsoft.availability.id Identifikator für diesen Testlauf.
microsoft.availability.name Name des Verfügbarkeitstests.
microsoft.availability.duration Testdauer, zum Beispiel 00:00:00.250.
microsoft.availability.success Ob der Test erfolgreich war.

microsoft.availability.runLocation und microsoft.availability.message sind optional. Wenn das Nachrichtenattribut weggelassen wird, wird der Logbuch als Verfügbarkeitsnachricht verwendet. Der Zeitstempel des Verfügbarkeitsergebnisses stammt aus dem OpenTelemetrie-Protokoll.

Verfügbarkeitsaufzeichnungen verwenden denselben Korrelationskontext wie andere OpenTelemetrie-Protokolle. Wenn ein Datensatz mit einem aktiven Span (oder einem expliziten OpenTelemetrie-Kontext) emittiert wird, füllen die Span-Trace-ID und SPAN-ID die Application Insights-Operations-ID und die Eltern-ID aus. Diese Werte sind autoritativ und können nicht durch Log-Attribute überschrieben werden. Die Verfügbarkeits-Testlauf-ID bleibt getrennt von der Operations-ID.

Wenn ein benötigtes Attribut fehlt oder leer ist, sendet der Exporter den Datensatz stattdessen als reguläre Nachrichtentelemetrie. Ausnahme- und benutzerdefinierte Ereignisattribute haben Vorrang vor Verfügbarkeitsattributen.

Probenahme

Sie können die Stichprobenerstellung aktivieren, um die Anzahl der empfangenen Telemetriedatensätze zu begrenzen. Um die korrekte Stichprobenerstellung in Application Insights zu aktivieren, verwenden Sie die ApplicationInsightsSampler wie unten gezeigt.

import { ApplicationInsightsSampler } from "@azure/monitor-opentelemetry-exporter";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

// Sampler expects a sample rate of between 0 and 1 inclusive
// A rate of 0.75 means approximately 75 % of your traces will be sent
const aiSampler = new ApplicationInsightsSampler(0.75);
const provider = new NodeTracerProvider({
  sampler: aiSampler,
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: "basic-service",
  }),
});

provider.register();

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.

Größenbegrenzung für benutzerdefinierte Maße

Standardmäßig werden benutzerdefinierte Dimensionswerte auf 64 KB abgeschnitten. Dies schützt vor unerwartet großen Nutzlasten.

Problembehandlung

Debugprotokollierung aktivieren

Sie können die Debugprotokollierung aktivieren, indem Sie den Protokollierungsgrad Ihres Anbieters ändern.

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";

const provider = new NodeTracerProvider();
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
provider.register();

Protokollierung

Das Aktivieren der Azure-Protokollierung kann auch dazu beitragen, nützliche Informationen zu Fehlern aufzudecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Dieser Exporter ist für die Verwendung mit dem OpenTelemetry JS konzipiert.

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