Azure Monitor OpenTelemetry voor JavaScript

Slag

Het pakket installeren

npm install @azure/monitor-opentelemetry

Momenteel ondersteunde omgevingen

• LTS-versies van Node.js

• ondersteunde runtimes van OpenTelemetry

Waarschuwing: deze SDK werkt alleen voor Node.js omgevingen. Gebruik de Application Insights JavaScript SDK- voor webbrowserscenario's.

Zie ons ondersteuningsbeleid voor meer informatie.

Voorwaarden

• Een Azure-abonnement
• Een Application Insights-werkruimte

Azure Monitor OpenTelemetry-client inschakelen

Belangrijk:useAzureMonitor moet worden aangeroepen voordat u iets anders importeert. Er kan telemetrieverlies optreden als andere bibliotheken eerst worden geïmporteerd.

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

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

• Verbindingsreeks kan worden ingesteld met behulp van de omgevingsvariabele APPLICATIONINSIGHTS_CONNECTION_STRING

Configuratie

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

const resource = new Resource({ 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);

Optie	Beschrijving	Verstek
azureMonitorExporterOptions	Configuratie van Azure Monitor OpenTelemetry Exporter. Meer informatie hier
samplingRatio	De steekproefverhouding moet een waarde in het bereik nemen [0,1], 1 wat betekent dat alle gegevens worden bemonsterd en 0 alle traceringsgegevens worden uitgemonsterd.	1
instrumentationOptions	Configuratie van instrumentatiebibliotheken. Meer informatie hier	{ http: { enabled: true }, azureSdk: { enabled: false }, mongoDb: { enabled: false }, mySql: { enabled: false }, postgreSql: { enabled: false }, redis: { enabled: false }, bunyan: { enabled: false }, winston: { enabled: false } }
browserSdkLoaderOptions	Configuratie van web-instrumentaties toestaan.	{ enabled: false, connectionString: "" }
resource	Opentelemetry-resource. Meer informatie hier
enableLiveMetrics	Live metrics in- of uitschakelen.	true
enableStandardMetrics	Standaardmetrieken in- of uitschakelen.	true
logRecordProcessors	Matrix van logboekrecordprocessors die moeten worden geregistreerd bij de globale logboekregistratieprovider.
spanProcessors	Matrix van spanprocessors die moeten worden geregistreerd bij de globale tracerprovider.
enableTraceBasedSamplingForLogs	Schakel logboeksampling in op basis van tracering.	false

Opties kunnen worden ingesteld met behulp van configuratiebestand applicationinsights.json zich onder de hoofdmap van @azure/monitor-opentelemetry installatiemap van het pakket, bijvoorbeeld: node_modules/@azure/monitor-opentelemetry. Deze configuratiewaarden worden toegepast op alle Exemplaren van AzureMonitorOpenTelemetryClient.

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

Er kan een aangepast JSON-bestand worden opgegeven met behulp van APPLICATIONINSIGHTS_CONFIGURATION_FILE omgevingsvariabele.

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

Instrumentatiebibliotheken

De volgende OpenTelemetry Instrumentation-bibliotheken zijn opgenomen als onderdeel van Azure Monitor OpenTelemetry.

Waarschuwing: Instrumentatiebibliotheken zijn gebaseerd op experimentele OpenTelemetry-specificaties. De preview-versie van Microsoft ondersteuning is ervoor te zorgen dat de volgende bibliotheken gegevens verzenden naar Azure Monitor Application Insights, maar het is mogelijk dat wijzigingen die fouten veroorzaken of experimentele toewijzing bepaalde gegevenselementen blokkeren.

Gedistribueerde tracering

• HTTP/HTTPS-
• MongoDB-
• MySQL-
• Postgres-
• Redis-
• Redis-4-
• Azure SDK-

Statistieken

• HTTP/HTTPS-

Logs

• Bunyan-

• Winston-

Andere OpenTelemetry Instrumentations zijn beschikbaar hier en kunnen worden toegevoegd met TracerProvider in 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()],
});

Application Insights Browser SDK-laadprogramma

Met Application Insights Browser SDK Loader kunt u de web-SDK injecteren in knooppuntserverreacties wanneer aan de volgende voorwaarden wordt voldaan:

• Antwoord heeft statuscode 200.
• De antwoordmethode is GET.
• Serverantwoord heeft de Conent-Type HTML-header.
• Serverresonse bevat zowel - als tags.
• Antwoord bevat geen huidige CDN-eindpunten voor /backup-web-instrumentatie. (huidige en back-up van CDN-eindpunten voor web instrumentatie hier)

Meer informatie over het gebruik van het browser-SDK-laadprogramma vindt u hier .

De naam van de cloudrol en het cloudrolexemplaren instellen

U kunt de naam van de cloudrol en het cloudrolexemplaren instellen via OpenTelemetry-resource kenmerken.

import { Resource } 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 = Resource.EMPTY;
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);

Zie Semantische conventies voor resources voor informatie over standaardkenmerken voor resources.

Telemetrie wijzigen

In deze sectie wordt uitgelegd hoe u telemetrie kunt wijzigen.

Spankenmerken toevoegen

Als u spankenmerken wilt toevoegen, gebruikt u een van de volgende twee manieren:

• Gebruik opties van instrumentatiebibliotheken.
• Voeg een aangepaste spanprocessor toe.

Deze kenmerken kunnen bestaan uit het toevoegen van een aangepaste eigenschap aan uw telemetrie.

Tip: Het voordeel van het gebruik van opties van instrumentatiebibliotheken, wanneer deze beschikbaar zijn, is dat de hele context beschikbaar is. Hierdoor kunnen gebruikers ervoor kiezen om meer kenmerken toe te voegen of te filteren. De verrijkingsoptie in de HttpClient-instrumentatiebibliotheek geeft gebruikers bijvoorbeeld toegang tot de httpRequestMessage zelf. Ze kunnen er alles uit selecteren en opslaan als een kenmerk.

Een aangepaste eigenschap toevoegen aan een tracering

Alle kenmerken u aan spanten toevoegt, worden geëxporteerd als aangepaste eigenschappen.

Een aangepaste processor gebruiken:

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

Bewerkingsnaam toevoegen aan traceringen en logboeken

Gebruik een aangepaste spanprocessor en logboekrecordprocessor om de naam van de bewerking te koppelen en correleren van aanvragen naar afhankelijkheden en logboeken.

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, LogRecord } 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: LogRecord, _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);

Telemetrie filteren

U kunt de volgende manieren gebruiken om telemetrie uit te filteren voordat deze uw toepassing verlaat.

1. Sluit de URL-optie uit van veel HTTP-instrumentatiebibliotheken.

   In het volgende voorbeeld ziet u hoe u een bepaalde URL kunt uitsluiten van bijgehouden met behulp van de HTTP/HTTPS-instrumentatiebibliotheek:

   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. Gebruik een aangepaste processor. U kunt een aangepaste spanprocessor gebruiken om bepaalde spanten uit te sluiten van het exporteren. Als u spanten wilt markeren die niet moeten worden geëxporteerd, stelt u TraceFlag in op DEFAULT. Gebruik het voorbeeld van aangepaste eigenschap toevoegen, maar vervang de volgende coderegels:

   ```ts snippet:ReadmeSampleCustomProcessor
   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;
       }
     }
   }
   ```
   

Aangepaste telemetrie

In deze sectie wordt uitgelegd hoe u aangepaste telemetriegegevens van uw toepassing verzamelt.

Aangepaste metrische gegevens toevoegen

Mogelijk wilt u metrische gegevens verzamelen buiten wat wordt verzameld door instrumentatiebibliotheken.

De OpenTelemetry-API biedt zes metrische 'instrumenten' voor verschillende metrische scenario's. U moet het juiste aggregatietype kiezen bij het visualiseren van metrische gegevens in Metrics Explorer. Deze vereiste geldt wanneer u de Metrische API voor OpenTelemetry gebruikt om metrische gegevens te verzenden en wanneer u een instrumentatiebibliotheek gebruikt.

In de volgende tabel ziet u de aanbevolen aggregatietypen] voor elk van de metrische instrumenten van OpenTelemetry.

OpenTelemetry Instrument	Azure Monitor-aggregatietype
Toonbank	Som
Asynchrone teller	Som
Histogram	Average, Sum, Count (Max, Min voor Python en alleen Node.js)
Asynchrone meter	Gemiddeld
UpDownCounter (alleen Python en Node.js)	Som
Asynchrone UpDownCounter (alleen Python en Node.js)	Som

Waarschuwing: Aggregatietypen buiten wat in de tabel wordt weergegeven, zijn doorgaans niet zinvol.

De OpenTelemetry Specification beschrijft de instrumenten en geeft voorbeelden van wanneer u deze kunt gebruiken.

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

Aangepaste uitzonderingen toevoegen

Selecteer instrumentatiebibliotheken ondersteunen automatisch uitzonderingen op Application Insights. Het is echter mogelijk dat u uitzonderingen handmatig wilt rapporteren buiten het rapport van instrumentiebibliotheken. Uitzonderingen die door uw code worden onderschept, worden bijvoorbeeld niet normaal gesproken niet gerapporteerd, en u kunt ze rapporteren en zo de aandacht vestigen op deze in relevante ervaringen, waaronder de blade fouten en de end-to-end transactieweergave.

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

Probleemoplossing

Zelfdiagnose

Azure Monitor OpenTelemetry maakt gebruik van de OpenTelemetry API Logger voor interne logboeken. Gebruik de volgende code om deze in te schakelen:

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 omgevingsvariabele kan worden gebruikt om het gewenste logboekniveau in te stellen, waarmee de volgende waarden worden ondersteund: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE en ALL.

Logboeken kunnen in een lokaal bestand worden geplaatst met behulp van APPLICATIONINSIGHTS_LOG_DESTINATION omgevingsvariabele, ondersteunde waarden worden file en file+console. Er wordt standaard een bestand met de naam applicationinsights.log gegenereerd op de tmp-map, inclusief alle logboeken, /tmp voor *nix en USERDIR/AppData/Local/Temp voor Windows. Logboekmap kan worden geconfigureerd met behulp van APPLICATIONINSIGHTS_LOGDIR omgevingsvariabele.

Voorbeelden

Zie de map samples/ voor volledige voorbeelden van enkele kampioenscenario's.

Sleutelbegrippen

Raadpleeg de OpenTelemetry Specificationsvoor meer informatie over het OpenTelemetry-project.

Invoegtoepassingsregister

Als u wilt zien of er al een invoegtoepassing is gemaakt voor een bibliotheek die u gebruikt, raadpleegt u de OpenTelemetry Registry.

Als u uw bibliotheek niet in het register kunt opnemen, kunt u een nieuwe invoegtoepassingsaanvraag voorstellen op opentelemetry-js-contrib.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.