Azure Monitor OpenTelemetry för JavaScript

Komma igång

Installera paketet

npm install @azure/monitor-opentelemetry

Miljöer som stöds för närvarande

• LTS-versioner av Node.js

• Körningar som stöds av OpenTelemetry

Varning: Detta SDK fungerar bara för Node.js miljöer. Använd Application Insights JavaScript SDK för webb- och webbläsarscenarier.

Mer information finns i vår supportprincip.

Förutsättningar

• En prenumeration på Azure
• En Application Insights-arbetsyta

Aktivera Azure Monitor OpenTelemetry-klienten

Viktig:useAzureMonitor måste anropas innan du importerar något annat. Det kan leda till telemetriförlust om andra bibliotek importeras först.

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

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

• Συμβολοσειρά APPLICATIONINSIGHTS_CONNECTION_STRINGσύνδεσ

Konfiguration

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: "" 
}
        
      

Alternativ kan ställas in med hjälp av konfigurationsfilen applicationinsights.json som finns under rotmappen i @azure/monitor-opentelemetry paketets installationsmapp, t.ex.: node_modules/@azure/monitor-opentelemetry. Dessa konfigurationsvärden tillämpas på alla AzureMonitorOpenTelemetryClient-instanser.

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

Anpassad JSON-fil kan tillhandahållas med hjälp av APPLICATIONINSIGHTS_CONFIGURATION_FILE miljövariabeln.

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

Instrumentationsbibliotek

Följande OpenTelemetry Instrumentation-bibliotek ingår som en del av Azure Monitor OpenTelemetry.

Not: Instrumentationerna Azure SDK, MongoDB, MySQL, PostgreSQL, Redis och Redis-4 är aktiverade som standard för distribuerad spårning. HTTP/HTTPS-instrumentationen är också aktiverad som standard. Alla andra instrumentationer är inaktiverade som standard och kan aktiveras genom att ange enabled: true i instrumentationsalternativen.

Varning: Instrumentationsbibliotek baseras på experimentella OpenTelemetry-specifikationer. Microsofts supportåtagande för förhandsversionen är att se till att följande bibliotek genererar data till Azure Monitor Application Insights, men det är möjligt att icke-bakåtkompatibla ändringar eller experimentell mappning blockerar vissa dataelement.

Distribuerad spårning

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

Mätvärden

• HTTP/HTTPS

Loggfiler

• Bunyan

• Winston

Andra OpenTelemetry-instrumentationer är tillgängliga här och kan läggas till med hjälp av TracerProvider i 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 SDK-inläsare för webbläsare

Med Application Insights Browser SDK Loader kan du mata in webb-SDK:n i nodserversvar när följande villkor är uppfyllda:

• Svaret har statuskoden 200.
• Svarsmetoden är GET.
• Serversvaret har html-huvudet Conent-Type .
• Serverresonse innehåller både och-taggar .
• Svaret innehåller inte aktuella /backup web Instrumentation CDN-slutpunkter. (aktuella och säkerhetskopierade CDN-slutpunkter för webbinstrumentation här)

Mer information om användningen av webbläsarens SDK-inläsare finns här.

Ange namnet på molnrollen och molnrollinstansen

Du kan ange namnet på molnrollen och molnrollinstansen via resursattributen 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);

Information om standardattribut för resurser finns i Resurssemantiska konventioner.

Ändra telemetri

I det här avsnittet beskrivs hur du ändrar telemetri.

Lägga till span-attribut

Om du vill lägga till span-attribut använder du något av följande två sätt:

• Använd alternativ som tillhandahålls av instrumentationsbibliotek.
• Lägg till en anpassad span-processor.

Dessa attribut kan vara att lägga till en anpassad egenskap i telemetrin.

Dricks: Fördelen med att använda alternativ som tillhandahålls av instrumentationsbibliotek, när de är tillgängliga, är att hela kontexten är tillgänglig. Därför kan användarna välja att lägga till eller filtrera fler attribut. Till exempel ger berika-alternativet i httpClient-instrumentationsbiblioteket användarna åtkomst till själva httpRequestMessage. De kan välja vad som helst från den och lagra den som ett attribut.

Lägga till en anpassad egenskap i en spårning

Alla attribut som du lägger till i intervall exporteras som anpassade egenskaper.

Använd en anpassad processor:

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

Lägga till åtgärdsnamn i spårningar och loggar

Använd en anpassad span-processor och loggpostprocessor för att bifoga och korrelera åtgärdsnamn från begäranden till beroenden och loggar.

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

Filtrera telemetridata

Du kan använda följande metoder för att filtrera bort telemetri innan den lämnar programmet.

1. Undanta URL-alternativet som tillhandahålls av många HTTP-instrumentationsbibliotek.

   I följande exempel visas hur du undantar en viss URL från att spåras med hjälp av HTTP/HTTPS-instrumentationsbiblioteket:

   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. Använd en anpassad processor. Du kan använda en anpassad span-processor för att undanta vissa intervall från att exporteras. Om du vill markera intervall som inte ska exporteras anger du TraceFlag till DEFAULT. Använd exemplet med att lägga till anpassad egenskap, men ersätt följande kodrader:

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

Anpassad telemetri

I det här avsnittet beskrivs hur du samlar in anpassad telemetri från ditt program.

Lägg till anpassade mått

Du kanske vill samla in mått utöver vad som samlas in av instrumentationsbibliotek.

OpenTelemetry-API:et erbjuder sex måttliga "instrument" för att täcka en mängd olika måttscenarier och du måste välja rätt "aggregeringstyp" när du visualiserar mått i Metrics Explorer. Det här kravet gäller när du använder OPENTelemetry Metric API för att skicka mått och när du använder ett instrumentationsbibliotek.

I följande tabell visas de rekommenderade aggregeringstyperna för vart och ett av de metriska OpenTelemetry-instrumenten.

Försiktighet: Aggregeringstyper utöver vad som visas i tabellen är vanligtvis inte meningsfulla.

OpenTelemetry-specifikationen beskriver instrumenten och ger exempel på när du kan använda var och en.

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

Lägg till anpassade undantag

Välj instrumentationsbibliotek stöder automatiskt undantag till Application Insights. Men du kanske vill rapportera undantag manuellt utöver vad instrumentionsbibliotek rapporterar. Undantag som fångas upp av din kod rapporteras till exempel vanligtvis inte , och du kanske vill rapportera dem och därmed dra uppmärksamhet till dem i relevanta upplevelser, inklusive felbladet och transaktionsvyn från slutpunkt till slutpunkt.

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

Felsökning

Självdiagnostik

Azure Monitor OpenTelemetry använder OpenTelemetry API-loggaren för interna loggar. Använd följande kod för att aktivera det:

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_LEVELMiljövariabeln kan användas för att ange önskad loggnivå, med stöd för följande värden: NONE, ERROR, WARNINFODEBUGVERBOSE, , och .ALL

Loggar kan placeras i en lokal fil med hjälp av APPLICATIONINSIGHTS_LOG_DESTINATION miljövariabeln, värden som stöds är file och file+console, en fil med namnet applicationinsights.log genereras på tmp-mappen som standard, inklusive alla loggar, /tmp för *nix och USERDIR/AppData/Local/Temp för Windows. Loggkatalogen kan konfigureras med hjälp av APPLICATIONINSIGHTS_LOGDIR miljövariabeln.

Exempel

Fullständiga exempel på några mästarscenarier finns i mappen samples/ .

Viktiga begrepp

Mer information om OpenTelemetry-projektet finns i OpenTelemetry-specifikationerna.

Plugin Registry

För att se om ett plugin-program redan har skapats för ett bibliotek som du använder, kolla in OpenTelemetry Registry.

Om du inte kan ditt bibliotek i registret kan du föreslå en ny plugin-begäran på opentelemetry-js-contrib.

Bidrag

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.