Azure Monitor OpenTelemetry voor JavaScript

Aan de slag

Installeer het pakket

npm install @azure/monitor-opentelemetry

Momenteel ondersteunde omgevingen

• LTS-versies van Node.js

• Door OpenTelemetry ondersteunde runtimes

Waarschuwing: Deze SDK werkt alleen voor Node.js omgevingen. Gebruik de Application Insights JavaScript SDK voor web- en browserscenario's.

Zie ons ondersteuningsbeleid voor meer informatie.

Vereiste 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 eerst andere bibliotheken 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);

• Connection String kan worden ingesteld met behulp van de omgevingsvariabele APPLICATIONINSIGHTS_CONNECTION_STRING.

Configuratie

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

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

        
{ 
  enabled: false, 
  connectionString: "" 
}
        
      

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

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

Een aangepast JSON-bestand kan worden verstrekt met behulp van APPLICATIONINSIGHTS_CONFIGURATION_FILE een omgevingsvariabele.

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

Instrumentatiebibliotheken

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

Notitie: De instrumentaties Azure SDK, MongoDB, MySQL, PostgreSQL, Redis en Redis-4 zijn standaard ingeschakeld voor gedistribueerde tracering. De HTTP/HTTPS-instrumentatie is ook standaard ingeschakeld. Alle andere instrumentaties zijn standaard uitgeschakeld en kunnen worden ingeschakeld door de instrumentatie-opties in te stellen enabled: true .

Waarschuwing: Instrumentatiebibliotheken zijn gebaseerd op experimentele OpenTelemetry-specificaties. De toezegging van Microsoft voor preview-ondersteuning is ervoor te zorgen dat de volgende bibliotheken gegevens verzenden naar Azure Monitor Application Insights, maar het is mogelijk dat belangrijke wijzigingen of experimentele toewijzingen sommige gegevenselementen blokkeren.

Gedistribueerde tracering

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

Statistieken

• HTTP/HTTPS

Logboeken

• Bunyan

• Winston

Andere OpenTelemetry-instrumentaties zijn hier beschikbaar en kunnen worden toegevoegd met behulp van 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-lader

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.
• Antwoordmethode is GET.
• Serverantwoord heeft de Conent-Type html-header.
• Serverresonse bevat zowel als tags.
• Antwoord bevat geen huidige CDN-eindpunten van /backup web Instrumentation. (huidige en back-up van WEB Instrumentation CDN-eindpunten hier)

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

De cloudrolnaam en de cloudrolexemplaar instellen

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

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

Zie Semantische conventies voor bronnen 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 die worden geboden door instrumentatiebibliotheken.
• Voeg een aangepaste spanprocessor toe.

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

Fooi: Het voordeel van het gebruik van opties die worden geboden door instrumentatiebibliotheken, wanneer deze beschikbaar zijn, is dat de volledige 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 die u aan spans 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 span-processor en een logboekrecordprocessor om de bewerkingsnaam toe te voegen en te 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, 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);

Telemetrie filteren

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

1. Sluit de URL-optie uit die door veel HTTP-instrumentatiebibliotheken wordt geboden.

   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 in op TraceFlagDEFAULT. Gebruik het voorbeeld van het toevoegen van aangepaste eigenschappen, maar vervang de volgende coderegels:

   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 die verder gaan dan wat wordt verzameld door instrumentatiebibliotheken.

De OpenTelemetry-API biedt zes metrische 'instrumenten' voor verschillende metrische scenario's en 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.

Voorzichtigheid: Aggregatietypen die verder gaan dan wat in de tabel wordt weergegeven, zijn meestal 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

Bepaalde instrumentatiebibliotheken bieden automatisch ondersteuning voor uitzonderingen op Application Insights. Het is echter mogelijk dat u handmatig uitzonderingen wilt rapporteren die verder gaan dan wat instrumentiebibliotheken rapporteren. Uitzonderingen die door uw code worden onderschept, worden bijvoorbeeld normaal gesproken niet gerapporteerd, en u kunt ze wel rapporteren en er zo de aandacht op vestigen in relevante ervaringen, waaronder de blade voor 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);
}

Probleemoplossingsproces

Zelfdiagnose

Azure Monitor OpenTelemetry maakt gebruik van de OpenTelemetry-APILOGGER voor interne logboeken. Gebruik de volgende code om dit 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 De omgevingsvariabele kan worden gebruikt om het gewenste logniveau in te stellen, waarbij 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 een omgevingsvariabele, ondersteunde waarden zijn file en file+console, een bestand met de naam applicationinsights.log wordt standaard gegenereerd in de tmp-map, inclusief alle logboeken, /tmp voor *nix en USERDIR/AppData/Local/Temp voor Windows. Logdirectory kan worden geconfigureerd met behulp van APPLICATIONINSIGHTS_LOGDIR omgevingsvariabele.

Voorbeelden

Zie de samples/ map voor volledige voorbeelden van een paar kampioensscenario's.

Belangrijke concepten

Raadpleeg de specificaties van OpenTelemetry voor meer informatie over het OpenTelemetry-project.

Plugin Register

Om te zien of er al een plug-in is gemaakt voor een bibliotheek die u gebruikt, raadpleegt u het OpenTelemetry-register.

Als u uw bibliotheek niet in het register kunt opnemen, kunt u een nieuw plug-inverzoek 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.