Azure Monitor OpenTelemetry JavaScripthez

NPM verzió

Kezdő lépések

A csomag telepítése

npm install @azure/monitor-opentelemetry

Jelenleg támogatott környezetek

Figyelmeztetés: Ez az SDK csak Node.js környezetekben működik. Használja az Application Insights JavaScript SDK-t webes és böngészős forgatókönyvekhez.

További részletekért tekintse meg támogatási szabályzatunkat.

Előfeltételek

Azure Monitor OpenTelemetry-ügyfél engedélyezése

Fontos:useAzureMonitor meg kell hívni, mielőtt bármi mást importálna. Telemetriavesztés következhet be, ha először más kódtárakat importál.

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

const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString:
      process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
  },
};
useAzureMonitor(options);
  • A kapcsolati lánc beállítható, hogy .APPLICATIONINSIGHTS_CONNECTION_STRING
  • A sampler az OpenTelemetry env vars OTEL_TRACES_SAMPLER és OTEL_TRACES_SAMPLER_ARG (az opcióval szemben samplingRatio ) beállítható. Támogatott mintavételi értékek: microsoft.rate_limited, microsoft.fixed_percentage, always_on, always_offtrace_id_ratioparentbased_always_onparentbased_always_off, , . parentbased_trace_id_ratio A microsoft.rate_limited, esetén az arg spans per másodperc; / trace_id_ratioparentbased esetén az arg valószínűsége [0,1]-ben. Ha az arg-t kihagyják, alapértelmezett értékek érvényesek (a sebességkorlát kikapcsolva; valószínűség alapértelmezett 1-re). A teljes kontextusért lásd az OpenTelemetry felső szintű környezeti változó specifikációját: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/.
  • A fix százalékos mintavételező (az alapértelmezett sebességkorlátozott mintavételező helyett) használata esetén például:
    • Állítsuk be a környezeti változót OTEL_TRACES_SAMPLER=microsoft.fixed_percentage opcionális OTEL_TRACES_SAMPLER_ARG mintázási valószínűséggel (pl. 0.5 50%esetén).
    • A tracesPerSecond: 0 disztribúció beállításokban beállítva, ami letiltja a sebességkorlátozást, és visszavezethető fix samplingRatio százalékos mintavételhez.

ESM támogatás

Megjegyzés: Az ESM támogatás Node.js 18.19.0 vagy újabb verziót igényel. Az OpenTelemetry-ben az ESM támogatásról további részletekért lásd az OpenTelemetry ESM Support dokumentációját.

ECMAScript modul (ESM) alkalmazásoknál az OpenTelemetry műszerkészítés megköveteli, hogy a töltő horgokat regisztrálják, mielőtt bármilyen műszeres modult (például httpbetöltenének). Ez az ESM alapvető követelménye – a modulokat nem lehet betölteni a betöltésük után.

Használja a --import zászlót, hogy a töltő a Node.js folyamat elején regisztrálva legyen. Cseréld <your-app-entry-point> le az alkalmazás fő fájljához vezető úttal (pl. ./dist/index.js, , ./src/index.mjs./server.js, , stb.):

node --import @azure/monitor-opentelemetry/loader <your-app-entry-point>

Például a package.json:

{
  "scripts": {
    "start": "node --import @azure/monitor-opentelemetry/loader ./dist/index.js"
  }
}

Ezután az alkalmazásbejegyzési fájlban hívd useAzureMonitor() az SDK konfigurálásához:

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

useAzureMonitor({
  azureMonitorExporterOptions: {
    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
  },
});

A CommonJS alkalmazásoknál nincs szükség további zászlókra – a töltő automatikusan regisztrálódik, amikor a csomagot importálják.

Konfiguráció

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 },
    // Console log collection is opt-in (disabled by default)
    console: { enabled: false },
  },
  enableLiveMetrics: true,
  enableStandardMetrics: true,
  browserSdkLoaderOptions: {
    enabled: false,
    connectionString: "",
  },
  resource: resource,
  logRecordProcessors: [],
  spanProcessors: [],
  views: [],
};
useAzureMonitor(options);
Lehetőség Leírás Alapértelmezett
azureMonitorExporterOptions Azure Monitor OpenTelemetry exportőr konfigurációja. További információ itt
samplingRatio A mintavételi aránynak [0,1], 1 tartományban kell lennie, vagyis minden adatot mintavételeznek, és 0 minden követési adatot mintavétel lesz. Csak akkor használják, ha tracesPerSecond 0-ra van állítva. 1
tracesPerSecond A maximális nyomok száma másodpercenként a sebességkorlátozott mintavételezővel. Állítsd 0-ra, hogy letiltsd a sebességkorlátozást, és helyette használj fix százalékos mintavételt samplingRatio . 5
instrumentationOptions Rendszerállapot-kódtárak konfigurálása. További információ itt 

{
  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 }, 
  console: { enabled: false } 
}
browserSdkLoaderOptions Webes rendszerállapotok konfigurálásának engedélyezése. 
        
{ 
  enabled: false, 
  connectionString: "" 
}
resource Opentelemetry erőforrás. További információ itt
enableLiveMetrics Élő metrikák engedélyezése/letiltása. true
enableStandardMetrics Standard metrikák engedélyezése/letiltása. true
logRecordProcessors A globális naplózó szolgáltatónál regisztrálandó naplórekord-feldolgozók tömbje.
spanProcessors A globális nyomkövetési szolgáltatónál regisztrálandó tartományfeldolgozók tömbje.
views Metrikus nézetek tömbje, amelyet regisztrálni lehet a globális mérő szolgáltatónál.
enableTraceBasedSamplingForLogs Napló-mintavételezés engedélyezése nyomkövetés alapján. false
enablePerformanceCounters Engedélyezze a teljesítményszámlálókat. true

Az opciókat a csomagtelepítési mappa applicationinsights.json gyökérmappájában található konfigurációs fájlban @azure/monitor-opentelemetry lehet megadni, pl.: node_modules/@azure/monitor-opentelemetry. Ezeket a konfigurációs értékeket a rendszer az összes AzureMonitorOpenTelemetryClient példányra alkalmazza.

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

Az egyéni JSON-fájl környezeti APPLICATIONINSIGHTS_CONFIGURATION_FILE változóval is megadható.

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

Műszerezési könyvtárak

A következő OpenTelemetry Instrumentation kódtárak a Azure Monitor OpenTelemetry részét képezik.

Megjegyzés: Az Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis és Redis-4 instrumentációk alapértelmezetten engedélyezettek elosztott követéshez. A HTTP/HTTPS rendszerállapot alapértelmezés szerint engedélyezve is van. Az összes többi rendszerállapot alapértelmezés szerint le van tiltva, és a rendszerállapot-beállítások beállításával enabled: true engedélyezhető.

Figyelmeztetés: A rendszerállapot-kódtárak kísérleti OpenTelemetria-specifikációkon alapulnak. A Microsoft előzetes verziójú támogatási kötelezettségvállalása annak biztosítása, hogy a következő kódtárak adatokat bocsátsanak ki az Azure Monitor Application Insightsba, de lehetséges, hogy a kompatibilitástörő módosítások vagy a kísérleti leképezés blokkol bizonyos adatelemeket.

Elosztott nyomkövetés

Mértékek

Naplók

  • Bunyan

  • Winston

  • Konzol (alapértelmezés szerint letiltva; engedélyezve )instrumentationOptions: { console: { enabled: true } }

    A bekapcsolás után a gyűjtött metódushalmazt console a APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL környezeti változó (NONE, ERROR, WARN, DEBUGALLINFOVERBOSE; lásd Öndiagnosztika) szűrik. Például WARN csak console.warn és console.errorés gyűjt, míg NONE teljesen letiltja a naplók (és az összes többi napló gyűjtését console .

Más OpenTelemetry Instrumentations itt érhető el, és a TracerProvider használatával adható hozzá az AzureMonitorOpenTelemetryClient szolgáltatásban.

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 böngésző SDK betöltő

Az Application Insights böngésző SDK betöltője lehetővé teszi a webes SDK beszúrását a csomópont-kiszolgáló válaszaiba, ha a következő feltételek teljesülnek:

  • A válasz állapotkóddal 200rendelkezik.
  • A válaszadási módszer: GET.
  • A kiszolgáló válasza a Conent-Type html fejlécet tartalmazza.
  • A szerverrezonzis tartalmazza mind a és címkéket .
  • A válasz nem tartalmaz aktuális /backup web Instrumentation CDN-végpontokat. (a Web Instrumentation CDN-végpontok aktuális és biztonsági mentése itt)

A böngésző SDK betöltő használatával kapcsolatos további információk itt találhatók.

A felhőbeli szerepkör nevének és a felhőbeli szerepkörpéldánynak a beállítása

A felhőbeli szerepkör nevét és a felhőbeli szerepkörpéldányt OpenTelemetry erőforrásattribútumokkal állíthatja be.

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

Az erőforrások szabványos attribútumaival kapcsolatos információkért lásd: Erőforrás-szemantikai konvenciók.

Telemetria módosítása

Ez a szakasz bemutatja, hogyan módosíthatja a telemetriát.

Span attribútumok hozzáadása

Span attribútumok hozzáadásához használja az alábbi két módszer egyikét:

Ezek az attribútumok közé tartozhat egy egyéni tulajdonság hozzáadása a telemetriához.

Borravaló: A rendszerállapot-kódtárak által biztosított lehetőségek használatának előnye, hogy a teljes környezet elérhető. Ennek eredményeképpen a felhasználók további attribútumokat adhatnak hozzá vagy szűrhetnek. A HttpClient-rendszerállapot-kódtár bővítési lehetősége például hozzáférést biztosít a felhasználóknak magához a httpRequestMessage-hez. Bármit kiválaszthatnak belőle, és attribútumként tárolhatják.

Egyéni tulajdonság hozzáadása nyomkövetéshez

A spanokhoz hozzáadott attribútumok egyéni tulajdonságokként lesznek exportálva.

Egyéni processzor használata:

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

Műveletnév hozzáadása nyomkövetésekhez és naplókhoz

Egyéni tartományfeldolgozó és naplórekord-feldolgozó használatával csatolhatja és korrelálhatja a műveletek nevét a kérésekből a függőségekhez és a naplókhoz.

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

Telemetria szűrése

A következő módszerekkel szűrheti ki a telemetriát, mielőtt az elhagyja az alkalmazást.

  1. Zárja ki a számos HTTP-eszköztár által biztosított URL-beállítást.

    Az alábbi példa bemutatja, hogyan zárhat ki egy bizonyos URL-címet a NYOMON követésből a HTTP/HTTPS-rendszerállapot-kódtár használatával:

    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. Használjon egyéni processzort. Egyéni span processzorral kizárhat bizonyos időtartamokat az exportálásból. Ha a spanokat nem exportálandóként szeretné megjelölni, állítsa a következőre TraceFlagDEFAULT: . Használja az egyéni tulajdonság hozzáadása példát, de cserélje le a következő kódsorokat:

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

Egyéni telemetria

Ez a szakasz bemutatja, hogyan gyűjthet egyéni telemetriát az alkalmazásból.

Egyéni mutatók hozzáadása

Érdemes lehet a rendszerállapot-kódtárak által gyűjtött metrikákon túl is gyűjteni.

Az OpenTelemetry API hat metrika "eszközt" kínál a különböző metrikaforgatókönyvek lefedéséhez, és a metrikák Metrikakezelőben való vizualizációja során ki kell választania a megfelelő "összesítési típust". Ez a követelmény akkor érvényes, ha az OpenTelemetry Metric API használatával metrikákat küld, és rendszerállapot-kódtárat használ.

Az alábbi táblázat az egyes OpenTelemetry metrikaeszközök ajánlott összesítési típusait mutatja be.

OpenTelemetry eszköz Azure Monitor aggregáció típusa
Számláló Összeg
Aszinkron számláló Összeg
Hisztogram Átlag, Összeg, Darabszám (Max, Min csak Python és Node.js esetén)
Aszinkron mérőműszer Átlagos érték
UpDownCounter (csak Python és Node.js) Összeg
Aszinkron UpDownCounter (csak Python és Node.js) Összeg

Figyelmeztet: A táblázatban láthatókon túlmutató összesítési típusok általában nem értelmesek.

Az OpenTelemetria specifikációja ismerteti az eszközöket, és példákat tartalmaz arra, hogy mikor használhatja az egyes eszközöket.

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

Egyéni kivételek hozzáadása

A rendszerállapot-kódtárak kiválasztása automatikusan támogatja az Application Insights kivételeit. Előfordulhat azonban, hogy manuálisan szeretné jelenteni a kivételeket az instrumention-kódtárak jelentésén túl. Például a kód által elkapott kivételeket általában nem jelenti a rendszer, és érdemes lehet jelenteni őket, és így felhívni rájuk a figyelmet a releváns tapasztalatokban, beleértve a hibák panelt és a végpontok közötti tranzakciós nézetet.

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

Hibaelhárítás

Öndiagnosztika

Azure Monitor OpenTelemetry az OpenTelemetry API-naplózót használja a belső naplókhoz. Az engedélyezéshez használja a következő kódot:

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_LEVEL környezeti változóval beállítható a kívánt naplózási szint, amely a következő értékeket támogatja: NONE, ERROR, WARN, INFO, DEBUG, és VERBOSEALL.

A naplókat a környezeti változó segítségével APPLICATIONINSIGHTS_LOG_DESTINATION lehet helyi fájlba helyezni, a támogatott értékek és file , file+consolealapértelmezés szerint egy nevű applicationinsights.log fájl jön létre a tmp mappában, beleértve az összes naplót, * /tmp nix és USERDIR/AppData/Local/Temp Windows esetén. A naplókönyvtár környezeti APPLICATIONINSIGHTS_LOGDIR változóval konfigurálható.

Példák

Néhány hősforgatókönyv teljes mintáját a mappában samples/ találja.

Főbb fogalmak

Az OpenTelemetry projekttel kapcsolatos további információkért tekintse át az OpenTelemetry specifikációit.

Plugin rendszerleíró adatbázis

Ha meg szeretné tudni, hogy készült-e már beépülő modul egy használt kódtárhoz, tekintse meg az OpenTelemetry beállításjegyzéket.

Ha nem tudja beírni a könyvtárát a rendszerleíró adatbázisba, nyugodtan javasoljon új bővítménykérést a címen opentelemetry-js-contrib.

Közreműködés

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót, amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

  • Last updated on