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

• OpenTelemetry-körningar som stöds

Varning: Den här SDK:n 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 Azure-prenumeration
• En Application Insights-arbetsyta

Aktivera Azure Monitor OpenTelemetry Client

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

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

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

• Anslutningssträng kan anges med hjälp av miljövariabeln APPLICATIONINSIGHTS_CONNECTION_STRING

Konfiguration

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

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

Egenskap	Beskrivning	Standard
azureMonitorExporterOptions	Konfiguration av Azure Monitor OpenTelemetry Exporter. Mer information här
samplingRatio	Samplingsförhållandet måste ta ett värde i intervallet [0,1], 1 vilket innebär att alla data samplas och 0 alla spårningsdata samplas ut.	1
instrumentationOptions	Tillåt konfiguration av OpenTelemetry Instrumentations.	{"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	Tillåt konfiguration av webbinstrumentationer.	{ aktiverat: false, connectionString: "" }
resurs	Opentelemetry-resurs. Mer information här
samplingRatio	Samplingsförhållandet måste ta ett värde i intervallet [0,1], 1 vilket innebär att alla data samplas och 0 alla spårningsdata samplas ut.	1
enableLiveMetrics	Aktivera/inaktivera livemått.	sann
enableStandardMetrics	Aktivera/inaktivera standardmått.	sann
logRecordProcessors	Matris med loggpostprocessorer som ska registreras till den globala loggningsprovidern.
spanProcessors	Matris med span-processorer som ska registreras till den globala spårningsprovidern.
enableTraceBasedSamplingForLogs	Aktivera loggsampling baserat på spårning.	falsk

Alternativ kan anges med hjälp av konfigurationsfilen applicationinsights.json finns under rotmappen för @azure/monitor-opentelemetry paketinstallationsmapp, till exempel 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övariabel.

process.env.APPLICATIONINSIGHTS_CONFIGURATION_FILE =
  "C:/applicationinsights/config/customConfig.json";

// Application Insights SDK setup....

Instrumentationsbibliotek

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

Varning: Instrumentationsbibliotek baseras på experimentella OpenTelemetry-specifikationer. Microsofts förhandsversion supportåtagande ä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-4
• Azure SDK

Metrik

• HTTP/HTTPS-

Loggar

• Bunyan

• Winston

Andra OpenTelemetry-instrumentationer är tillgängliga här och kan läggas till med TracerProvider i AzureMonitorOpenTelemetryClient.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { metrics, trace } from "@opentelemetry/api";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

useAzureMonitor();
const instrumentations = [new ExpressInstrumentation()];
registerInstrumentations({
  tracerProvider: trace.getTracerProvider(),
  meterProvider: metrics.getMeterProvider(),
  instrumentations: instrumentations,
});

Application Insights Browser SDK-inläsare

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

• Svaret har statuskoden 200.
• Svarsmetoden är GET.
• Serversvaret har Conent-Type html-sidhuvud.
• Serverresons innehåller både - och -taggar.
• Svaret innehåller inte aktuella /backup web Instrumentation CDN-slutpunkter. (aktuella cdn-slutpunkter för webbinstrumentation och säkerhetskopiering 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 molnrollnamnet och molnrollinstansen via OpenTelemetry-resurs attribut.

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

// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const customResource = Resource.EMPTY;
customResource.attributes[SemanticResourceAttributes.SERVICE_NAME] = "my-helloworld-service";
customResource.attributes[SemanticResourceAttributes.SERVICE_NAMESPACE] = "my-namespace";
customResource.attributes[SemanticResourceAttributes.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.

Tips: 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 { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
import { SemanticAttributes } from "@opentelemetry/semantic-conventions";

class SpanEnrichingProcessor implements SpanProcessor {
  forceFlush(): Promise<void> {
    return Promise.resolve();
  }
  shutdown(): Promise<void> {
    return Promise.resolve();
  }
  onStart(_span: Span): void {}
  onEnd(span: ReadableSpan) {
    span.attributes["CustomDimension1"] = "value1";
    span.attributes["CustomDimension2"] = "value2";
    span.attributes[SemanticAttributes.HTTP_CLIENT_IP] = "<IP Address>";
  }
}

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
  // Add the SpanEnrichingProcessor
  spanProcessors: [new SpanEnrichingProcessor()],
};
useAzureMonitor(options);

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

Använd en processor för anpassat intervall och en loggpostprocessor för att bifoga och korrelera åtgärdsnamnet från begäranden till beroenden och loggar.

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
import { LogRecordProcessor } from "@opentelemetry/sdk-logs";
import { SemanticAttributes } from "@opentelemetry/semantic-conventions";
import { AI_OPERATION_NAME } from "@azure/monitor-opentelemetry-exporter";
import { Context, trace } from "@opentelemetry/api";

class SpanEnrichingProcessor implements SpanProcessor {
  forceFlush(): Promise<void> {
    return Promise.resolve();
  }
  shutdown(): Promise<void> {
    return Promise.resolve();
  }
  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.attributes[AI_OPERATION_NAME] = (parentSpan as unknown as ReadableSpan).name;
    }
  }
  onEnd(span: ReadableSpan) {}
}

class LogRecordEnrichingProcessor implements LogRecordProcessor {
  forceFlush(): Promise<void> {
    return Promise.resolve();
  }
  shutdown(): Promise<void> {
    return Promise.resolve();
  }
  onEmit(_logRecord, _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.attributes[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 telemetri

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

1. Exkludera 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 {
     useAzureMonitor,
     AzureMonitorOpenTelemetryOptions,
   } from "@azure/monitor-opentelemetry";
   import { IncomingMessage } from "http";
   import { RequestOptions } from "https";
   import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
   
   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 lägg till anpassad egenskap, men ersätt följande kodrader:

   ```typescript
   ...
   import { SpanKind, TraceFlags } from "@opentelemetry/api";
   import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
   
   class SpanEnrichingProcessor implements SpanProcessor {
       ...
   
       onEnd(span: ReadableSpan) {
           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ägga 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åttinstrument för att täcka en mängd olika måttscenarier och du måste välja rätt sammansättningstyp 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 måttinstrumenten OpenTelemetry.

OpenTelemetry-instrument	Sammansättningstyp för Azure Monitor
Räknare	Summa
Asynkron räknare	Summa
Histogram	Average, Sum, Count (Max, Min för Python och endast Node.js)
Asynkron mätare	Genomsnitt
UpDownCounter (endast Python och Node.js)	Summa
Asynkron UpDownCounter (endast Python och Node.js)	Summa

Varning: sammansättningstyper 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 { ObservableResult, metrics } from "@opentelemetry/api";

useAzureMonitor();
const meter = metrics.getMeter("testMeter");

let histogram = meter.createHistogram("histogram");
let counter = meter.createCounter("counter");
let gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
  let 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. Du kanske dock vill rapportera undantag manuellt utöver vad instrumentionsbibliotek rapporterar. Till exempel är undantag som fångas av koden inte normalt inte rapporteras, och du kanske vill rapportera dem och därmed uppmärksamma 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");

let 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 Logger för interna loggar. Om du vill aktivera den använder du följande kod:

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

process.env.APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL = "VERBOSE";
process.env.APPLICATIONINSIGHTS_LOG_DESTINATION = "file";
process.env.APPLICATIONINSIGHTS_LOGDIR = "C:/applicationinsights/logs";

useAzureMonitor();

APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL miljövariabel kan användas för att ange önskad loggnivå med stöd för följande värden: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE och ALL.

Loggar kan placeras i en lokal fil med hjälp av APPLICATIONINSIGHTS_LOG_DESTINATION miljövariabel, värden som stöds är file och file+consolegenereras en fil med namnet applicationinsights.log 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övariabel.

Exempel

Fullständiga exempel på några avancerade scenarier finns i mappen samples/.

Viktiga begrepp

Mer information om OpenTelemetry-projektet finns i OpenTelemetry Specifications.

Plugin-register

Om du vill se om ett plugin-program redan har skapats för ett bibliotek som du använder kan du läsa OpenTelemetry Registry-.

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

Bidragande

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.