Azure Monitor OpenTelemetry JavaScripthez

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-előfizetés
Application Insights-munkaterület

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 karakterlánc a környezeti változóval APPLICATIONINSIGHTS_CONNECTION_STRINGállítható be.

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 },
  },
  enableLiveMetrics: true,
  enableStandardMetrics: true,
  browserSdkLoaderOptions: {
    enabled: false,
    connectionString: "",
  },
  resource: resource,
  logRecordProcessors: [],
  spanProcessors: [],
};
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 a [0,1] tartományban kell lennie, 1, ami azt jelenti, hogy minden adat mintavételezésre kerül, és 0 az összes nyomkövetési adatot ki kell venni.	`1`
`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 } }`
`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.
`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.

Jegyzet: Az Azure SDK, a MongoDB, a MySQL, a PostgreSQL, a Redis és a Redis-4 kialakítások alapértelmezés szerint engedélyezve vannak az elosztott nyomkö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

HTTP/HTTPS

Naplók

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:

Használja az instrumentációs könyvtárak által kínált lehetőségeket.
Adjon hozzá egy egyéni span processzort.

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.

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

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.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-11-14