Delen via

Azure Monitor OpenTelemetry voor JavaScript

  • Artikel

npm-versie

Aan de slag

Het pakket installeren

npm install @azure/monitor-opentelemetry

Momenteel ondersteunde omgevingen

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.

Vereisten

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 { useAzureMonitor, AzureMonitorOpenTelemetryOptions } 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 { 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);
Eigenschap Beschrijving Standaard
azureMonitorExporterOptions Configuratie van Azure Monitor OpenTelemetry Exporter. Meer informatie vindt u hier
samplingRatio De steekproefverhouding moet een waarde in het bereik [0,1] nemen. 1 betekent dat alle gegevens worden bemonsterd en 0 alle traceringsgegevens worden bemonsterd. 1
instrumentationOptions Configuratie van OpenTelemetry-instrumentaties toestaan. {"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 webinstrumenten toestaan. { enabled: false, connectionString: "" }
resource Opentelemetry-resource. Meer informatie vindt u hier
samplingRatio De steekproefverhouding moet een waarde in het bereik [0,1] nemen. 1 betekent dat alle gegevens worden bemonsterd en 0 alle traceringsgegevens worden bemonsterd. 1
enableLiveMetrics Metrische livegegevens in-/uitschakelen. onjuist
enableStandardMetrics Standaard metrische gegevens in-/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.

Opties kunnen worden ingesteld met behulp van het configuratiebestand applicationinsights.json onder de hoofdmap van @azure/monitor-opentelemetry de pakketinstallatiemap, 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
        }
    },
    ...
}

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

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

// Application Insights SDK setup....

Instrumentatiebibliotheken

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

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 wijzigingen die fouten veroorzaken of experimentele toewijzing sommige gegevenselementen blokkeren.

Gedistribueerde tracering

Metrische gegevens

Logboeken

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

Met het Application Insights Browser SDK-laadprogramma kunt u de web-SDK injecteren in knooppuntserverantwoorden wanneer aan de volgende voorwaarden wordt voldaan:

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

De naam van de cloudrol en het cloudrolexemplaren instellen

U kunt de naam van de cloudrol en het cloudrolexemplaren instellen via opentelemetry-resourcekenmerken .

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

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

Telemetrie wijzigen

In deze sectie wordt uitgelegd hoe u telemetrie wijzigt.

Span-kenmerken toevoegen

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

Deze kenmerken omvatten mogelijk 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 volledige context beschikbaar is. Als gevolg hiervan kunnen gebruikers selecteren om meer kenmerken toe te voegen of te filteren. De verrijkingsoptie in de instrumentatiebibliotheek HttpClient geeft gebruikers bijvoorbeeld toegang tot de httpRequestMessage zelf. Ze kunnen alles selecteren en opslaan als een kenmerk.

Een aangepaste eigenschap toevoegen aan een tracering

Kenmerken die u aan spans toevoegt, worden geëxporteerd als aangepaste eigenschappen.

Een aangepaste processor gebruiken:

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

Telemetrie filteren

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

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

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

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

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

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. U moet het juiste aggregatietype kiezen bij het visualiseren van metrische gegevens in Metrics Explorer. Deze vereiste geldt wanneer u de Metrische Api van 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
Prestatiemeteritem Sum
Asynchrone teller Sum
Histogram Gemiddelde, Som, Aantal (alleen max, min voor Python en Node.js)
Asynchrone meter Gemiddeld
UpDownCounter (alleen Python en Node.js) Sum
Asynchrone UpDownCounter (alleen Python en Node.js) Sum

Voorzichtigheid: Aggregatietypen die verder gaan dan wat in de tabel wordt weergegeven, zijn doorgaans niet zinvol.

De OpenTelemetry-specificatie beschrijft de instrumenten en geeft voorbeelden van wanneer u elk instrument kunt gebruiken.

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

Aangepaste uitzonderingen toevoegen

Geselecteerde instrumentatiebibliotheken ondersteunen automatisch uitzonderingen voor 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 opgevangen, worden bijvoorbeeld niet gewoonlijk niet gerapporteerd en u kunt ze rapporteren en de aandacht erop vestigen in relevante ervaringen, waaronder de blade fouten en de end-to-end transactieweergave.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { trace } 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);
}

Problemen oplossen

Zelfdiagnose

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

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 omgeving varialbe kan worden gebruikt om het gewenste logboekniveau in te stellen, met ondersteuning voor de volgende waarden: NONE, ERROR, WARN, INFO, DEBUGen VERBOSEALL.

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

Voorbeelden

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

Belangrijkste concepten

Raadpleeg de Specificaties van OpenTelemetry voor meer informatie over het Project OpenTelemetry.

Invoegtoepassingsregister

Als u wilt zien of er al een invoegtoepassing is gemaakt voor een bibliotheek die u gebruikt, raadpleegt u het OpenTelemetry-register.

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

Bijdragen

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

Weergaven