Azure Monitor OpenTelemetry pro JavaScript

Začínáme

Nainstalujte balíček .

npm install @azure/monitor-opentelemetry

Aktuálně podporovaná prostředí

Varování: Tato sada SDK funguje pouze pro Node.js prostředí. Použijte sadu Application Insights JavaScript SDK pro webové scénáře a scénáře prohlížeče.

Další podrobnosti najdete v zásadách podpory.

Požadavky

Povolení klienta OpenTelemetry služby Azure Monitor

Důležitý:useAzureMonitor musí být volána před importem čehokoli jiného. Pokud se nejprve importují jiné knihovny, může dojít ke ztrátě telemetrie.

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

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

Připojovací řetězec lze nastavit pomocí proměnné APPLICATIONINSIGHTS_CONNECTION_STRINGprostředí .

Konfigurace

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

Možnost	Popis	Výchozí
`azureMonitorExporterOptions`	Konfigurace exportéru OpenTelemetry služby Azure Monitor. Více informací zde
`samplingRatio`	Vzorkovací poměr musí nabývat hodnoty v rozsahu [0,1], 1, což znamená, že budou vzorkována všechna data a 0 budou vzorkována všechna trasová.	`1`
`instrumentationOptions`	Konfigurace instrumentačních knihoven. Více informací zde	`{ 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`	Povolit konfiguraci Web Instrumentation.	`{ enabled: false, connectionString: "" }`
`resource`	Prostředek Opentelemetry. Více informací zde
`enableLiveMetrics`	Povolí/zakáže živé metriky.	`true`
`enableStandardMetrics`	Povolí/zakáže standardní metriky.	`true`
`logRecordProcessors`	Pole procesorů záznamů protokolů k registraci u globálního poskytovatele záznamníků.
`spanProcessors`	Pole procesorů rozsahu pro registraci u globálního poskytovatele sledování.
`enableTraceBasedSamplingForLogs`	Povolte vzorkování protokolu na základě trasování.	`false`
`enablePerformanceCounters`	Povolte čítače výkonu.	`true`

Možnosti lze nastavit pomocí konfiguračního souboru applicationinsights.json umístěného v kořenové složce @azure/monitor-opentelemetry instalační složky balíčku, např. node_modules/@azure/monitor-opentelemetry: . Tyto hodnoty konfigurace se použijí na všechny AzureMonitorOpenTelemetryClient instance.

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

Vlastní soubor JSON lze poskytnout pomocí APPLICATIONINSIGHTS_CONFIGURATION_FILE proměnné prostředí.

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

Knihovny instrumentace

Následující knihovny OpenTelemetry Instrumentation jsou součástí Azure Monitor OpenTelemetry.

Poznámka: Instrumentace Azure SDK, MongoDB, MySQL, PostgreSQL, Redis a Redis-4 jsou ve výchozím nastavení povolené pro distribuované trasování. Ve výchozím nastavení je také povolena instrumentace HTTP/HTTPS. Všechny ostatní přístroje jsou ve výchozím nastavení zakázány a lze je povolit nastavením enabled: true v možnostech přístrojového vybavení.

Varování: Knihovny instrumentace jsou založené na experimentálních specifikacích OpenTelemetry. Závazek společnosti Microsoft v oblasti podpory verze Preview je zajistit, aby následující knihovny generovaly data do služby Azure Monitor Application Insights, ale je možné, že zásadní změny nebo experimentální mapování zablokují některé datové prvky.

Distribuované trasování

Metodiky

Protokol HTTP/HTTPS

Záznamy

Další instrumentace OpenTelemetry jsou k dispozici tady a je možné je přidat pomocí TracerProvider v 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()],
});

Zavaděč sady SDK prohlížeče Application Insights

Zavaděč sady SDK prohlížeče Application Insights umožňuje vložit webovou sadu SDK do odpovědí serveru uzlu, pokud jsou splněny následující podmínky:

Odpověď má stavový kód 200.
Metoda odpovědi je GET.
Odpověď serveru má html hlavičku Conent-Type .
Server resonse obsahuje oba tagy a .
Odpověď neobsahuje aktuální ani záložní koncové body CDN pro webovou instrumentaci. (aktuální a záložní CDN koncové body pro webovou instrumentaci zde)

Další informace o použití zavaděče SDK prohlížeče naleznete zde.

Nastavení názvu cloudové role a instance cloudové role

Název cloudové role a instanci cloudové role můžete nastavit prostřednictvím atributů prostředků 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);

Informace o standardních atributech pro zdroje naleznete v tématu Sémantické konvence prostředků.

Úprava telemetrie

Tato část vysvětluje, jak upravit telemetrii.

Přidání atributů span

Pokud chcete přidat atributy span, použijte jeden z následujících dvou způsobů:

Použijte možnosti poskytované knihovnami instrumentace.
Přidání vlastního procesoru span

Mezi tyto atributy může patřit přidání vlastní vlastnosti do telemetrie.

Spropitné: Výhodou použití možností poskytovaných knihovnami instrumentace, pokud jsou k dispozici, je to, že je k dispozici celý kontext. V důsledku toho mohou uživatelé vybrat přidání nebo filtrování dalších atributů. Například možnost rozšiřování v knihovně instrumentace HttpClient poskytuje uživatelům přístup k samotné httpRequestMessage. Můžou z něj vybrat cokoli a uložit ho jako atribut.

Přidání vlastní vlastnosti do trasování

Všechny atributy , které přidáte do rozsahů, se exportují jako vlastní vlastnosti.

Použití vlastního procesoru:

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

Přidání názvu operace do trasování a protokolů

Použijte vlastní procesor rozsahu a procesor záznamů protokolů, abyste mohli připojit a korelovat název operace z požadavků na závislosti a protokoly.

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

Filtrování telemetrie

Můžete použít následující způsoby k odfiltrování telemetrie předtím, než opustí vaši aplikaci.

Vylučte možnost adresy URL, kterou poskytuje mnoho knihoven instrumentace HTTP.

Následující příklad ukazuje, jak vyloučit určitou adresu URL ze sledování pomocí knihovny instrumentace 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);

Použijte vlastní procesor. Vlastní procesor span můžete použít k vyloučení určitých rozsahů z exportu. Pokud chcete označit rozsahy, které se nemají exportovat, nastavte TraceFlag na DEFAULThodnotu . Použijte příklad přidání vlastní vlastnosti, ale nahraďte následující řádky kódu:

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

Vlastní telemetrie

Tato část vysvětluje, jak shromažďovat vlastní telemetrická data z vaší aplikace.

Přidání vlastních metrik

Možná budete chtít shromažďovat metriky nad rámec toho, co shromažďují knihovny instrumentace.

Rozhraní OpenTelemetry API nabízí šest "nástrojů" metrik, které pokrývají celou řadu scénářů metrik, a při vizualizaci metrik v Průzkumníku metrik budete muset vybrat správný typ agregace. Tento požadavek platí při použití rozhraní API metriky OpenTelemetry k odesílání metrik a při použití knihovny instrumentace.

Následující tabulka uvádí doporučené typy agregací pro každý z metrických nástrojů OpenTelemetry.

OpenTelemetry nástroj	Typ agregace služby Azure Monitor
Počítadlo	Suma
Asynchronní čítač	Suma
Histogram	Průměr, Součet, Počet (Max, Min pouze pro Python a Node.js)
Asynchronní měřidlo	Průměr
UpDownCounter (pouze Python a Node.js)	Suma
Asynchronní UpDownCounter (pouze Python a Node.js)	Suma

Opatrnost: Typy agregace nad rámec toho, co je uvedeno v tabulce, obvykle nejsou smysluplné.

Specifikace OpenTelemetry popisuje nástroje a poskytuje příklady, kdy je možné jednotlivé nástroje použít.

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

Přidání vlastních výjimek

Vybrané knihovny instrumentace automaticky podporují výjimky z Application Insights. Můžete však chtít ručně hlásit výjimky nad rámec toho, co hlásí knihovny nástrojů. Například výjimky zachycené vaším kódem nejsou obvykle hlášeny a můžete je chtít nahlásit a upozornit na ně v relevantních prostředích, včetně okna selhání a zobrazení transakcí typu 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);
}

Řešení problémů

Samoobslužná diagnostika

Azure Monitor OpenTelemetry používá pro interní protokoly protokolovací nástroj rozhraní API OpenTelemetry. Chcete-li jej povolit, použijte následující kód:

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_LEVELProměnnou prostředí lze použít k nastavení požadované úrovně protokolu, která podporuje následující hodnoty: NONE, ERROR, WARN, INFODEBUGVERBOSE a .ALL

Logy mohou být vloženy do lokálního souboru pomocí APPLICATIONINSIGHTS_LOG_DESTINATION environment variable, podporované hodnoty jsou file a file+console, soubor s názvem applicationinsights.log bude implicitně vygenerován ve složce tmp, včetně všech logů, /tmp pro *nix a USERDIR/AppData/Local/Temp pro Windows. Adresář protokolu lze konfigurovat pomocí APPLICATIONINSIGHTS_LOGDIR proměnné prostředí.

Příklady

Kompletní ukázky několika scénářů se šampiony najdete ve samples/ složce.

Klíčové koncepty

Další informace o projektu OpenTelemetry najdete ve specifikacích OpenTelemetry.

Registr pluginů

Pokud chcete zjistit, jestli už byl modul plug-in vytvořen pro knihovnu, kterou používáte, podívejte se na registr OpenTelemetry.

Pokud nemůžete svou knihovnu v registru, neváhejte navrhnout nový požadavek na plugin na opentelemetry-js-contrib.

Přispění

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-14