OpenTelemetry služby Azure Monitor pro JavaScript

Článek
05/15/2024

Začínáme

Instalace balíčku

npm install @azure/monitor-opentelemetry

Aktuálně podporovaná prostředí

Upozornění: Tato sada SDK funguje jenom pro Node.js prostředí. Pro webové scénáře a scénáře prohlížeče použijte sadu Application Insights JavaScript SDK .

Další podrobnosti najdete v našich zásadách podpory .

Požadavky

Povolení klienta OpenTelemetry služby Azure Monitor

Důležité:useAzureMonitor Před importem čehokoli dalšího musí být volána . Pokud se nejprve naimportují jiné knihovny, může dojít ke ztrátě telemetrie.

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

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

Připojovací řetězec je možné nastavit pomocí proměnné prostředí APPLICATIONINSIGHTS_CONNECTION_STRING

Konfigurace

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

Vlastnost	Popis	Default
azureMonitorExporterOptions	Konfigurace exportéru OpenTelemetry pro Azure Monitor. Další informace najdete tady.
samplingRatio	Vzorkovací poměr musí převzít hodnotu v rozsahu [0,1], což znamená, že všechna data budou vzorkována a 0 všechna data trasování budou odebrána.	1
instrumentationOptions	Povolte konfiguraci 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	Povolit konfiguraci webových instrumentací.	{ enabled: false, connectionString: "" }
prostředek	Opentelemetry – prostředek. Další informace najdete tady.
samplingRatio	Vzorkovací poměr musí převzít hodnotu v rozsahu [0,1], což znamená, že všechna data budou vzorkována a 0 všechna data trasování budou odebrána.	1
enableLiveMetrics	Povolit nebo zakázat živé metriky.	false (nepravda)
enableStandardMetrics	Povolte nebo zakažte standardní metriky.	true
logRecordProcessors	Pole procesorů záznamů protokolu pro registraci u globálního poskytovatele protokolovacího nástroje.
spanProcessors	Pole procesorů span pro registraci ke globálnímu poskytovateli trasování.

Možnosti lze nastavit pomocí konfiguračního souboru applicationinsights.json umístěného @azure/monitor-opentelemetry v kořenové složce instalační složky balíčku, například node_modules/@azure/monitor-opentelemetry. Tyto konfigurační hodnoty se použijí pro všechny instance AzureMonitorOpenTelemetryClient.

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

Vlastní soubor JSON je možné poskytnout pomocí APPLICATIONINSIGHTS_CONFIGURATION_FILE proměnné prostředí.

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

// Application Insights SDK setup....

Knihovny instrumentace

Následující knihovny OpenTelemetry Instrumentation jsou součástí OpenTelemetry služby Azure Monitor.

Upozornění: Knihovny instrumentace jsou založené na experimentálních specifikacích OpenTelemetry. Microsoft se zavazuje k podpoře verze Preview zajistit, aby následující knihovny vysílaly data do služby Azure Monitor Application Insights, ale je možné, že změny způsobující chybu nebo experimentální mapování některé datové prvky zablokují.

Distribuované trasování

Metriky

HTTP/HTTPS

Protokoly

Další instrumentace OpenTelemetry jsou k dispozici tady a je možné je přidat pomocí TracerProvider v 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 Loader

Application Insights Browser SDK Loader umožňuje vložit webovou sadu SDK do odpovědí serveru uzlu, pokud jsou splněny následující podmínky:

Odpověď má stavový kód 200.
Metoda odpovědi je GET.
Odpověď serveru má hlavičku Conent-Type html.
Rezonse serveru obsahuje značky a .
Odpověď neobsahuje aktuální koncové body CDN webové instrumentace /backup. (aktuální a zálohovací koncové body CDN webové instrumentace zde)

Nastavení názvu cloudové role a instance cloudové role

Název cloudové role a instanci cloudové role můžete nastavit prostřednictvím atributů prostředků OpenTelemetry .

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

Informace o standardních atributech pro prostředky najdete v tématu sémantické konvence prostředků.

Úprava telemetrie

Tato část vysvětluje, jak upravit telemetrii.

Přidání atributů span

Pokud chcete přidat atributy span, použijte jeden z následujících dvou způsobů:

Použijte možnosti poskytované knihovnami instrumentace.
Přidejte vlastní procesor span.

Mezi tyto atributy může patřit přidání vlastní vlastnosti do telemetrie.

Tip: Výhodou použití možností poskytovaných knihovnami instrumentace, pokud jsou dostupné, je, že je k dispozici celý kontext. V důsledku toho si uživatelé můžou vybrat přidání nebo filtrování dalších atributů. Například možnost enrich v knihovně instrumentace HttpClient poskytuje uživatelům přístup k samotné httpRequestMessage. Můžou z něj vybrat cokoli a uložit to jako atribut.

Přidání vlastní vlastnosti do trasování

Všechny atributy, které přidáte do rozsahů, se exportují jako vlastní vlastnosti.

Použití vlastního procesoru:

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

Filtrování telemetrie

Můžete použít následující způsoby, jak vyfiltrovat telemetrii předtím, než opustí vaši aplikaci.

Vylučte možnost adresy URL, kterou poskytuje mnoho knihoven instrumentace HTTP.

Následující příklad ukazuje, jak vyloučit určitou adresu URL ze sledování pomocí knihovny instrumentace HTTP/HTTPS:

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

Použijte vlastní procesor. K vyloučení určitých rozsahů z exportu můžete použít vlastní procesor span. Pokud chcete označit rozsahy, aby se neexportovaly, nastavte TraceFlag na DEFAULT. Použijte příklad přidání vlastní vlastnosti, ale nahraďte následující řádky kódu:

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

Vlastní telemetrická data

Tato část vysvětluje, jak shromažďovat vlastní telemetrii z vaší aplikace.

Přidání vlastních metrik

Možná budete chtít shromažďovat metriky nad rámec toho, co shromažďují knihovny instrumentace.

Rozhraní API OpenTelemetry nabízí šest "nástrojů" metrik pro pokrytí různých scénářů metrik a při vizualizaci metrik v Průzkumníku metrik budete muset vybrat správný typ agregace. Tento požadavek platí při použití rozhraní Api pro metriky OpenTelemetry k odesílání metrik a při použití knihovny instrumentace.

V následující tabulce jsou uvedeny doporučené typy agregace] pro jednotlivé nástroje metriky OpenTelemetry.

OpenTelemetry Instrument	Typ agregace služby Azure Monitor
Čítač	Sum
Asynchronní čítač	Sum
Histogram	Průměr, Součet, Počet (pouze maximální, minimální pro Python a Node.js)
Asynchronní měřidlo	Průměr
UpDownCounter (jenom Python a Node.js)	Sum
Asynchronní UpDownCounter (jenom Python a Node.js)	Sum

Pozor: Typy agregace nad rámec toho, co je znázorněno v tabulce, obvykle nemají smysl.

Specifikace OpenTelemetry popisuje nástroje a poskytuje příklady, kdy můžete použít každý z nich.

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

Přidání vlastních výjimek

Výběr knihoven instrumentace automaticky podporuje výjimky z Application Insights. Můžete ale chtít ručně hlásit výjimky nad rámec toho, co hlásí knihovny instrumention. Například výjimky zachycené vaším kódem se obvykle neohlašují a můžete je chtít nahlásit, a tím na ně upozornit v relevantních prostředích, včetně okna selhání a zobrazení kompletních transakcí.

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

Poradce při potížích

Autodiagnostika

Azure Monitor OpenTelemetry používá pro interní protokoly protokolovací nástroj rozhraní API OpenTelemetry. Pokud ho chcete povolit, použijte následující kód:

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_LEVELVarialbe prostředí je možné použít k nastavení požadované úrovně protokolu, která podporuje následující hodnoty: , , , , , a VERBOSEALL. DEBUGINFOWARNERRORNONE

Protokoly je možné vložit do místního souboru pomocí APPLICATIONINSIGHTS_LOG_DESTINATION proměnné prostředí, podporované hodnoty jsou file a file+console. Ve složce tmp se ve výchozím nastavení vygeneruje soubor s názvem applicationinsights.log , včetně všech protokolů, /tmp pro *nix a USERDIR/AppData/Local/Temp pro Windows. Adresář protokolu je možné nakonfigurovat pomocí APPLICATIONINSIGHTS_LOGDIR proměnné prostředí.

Příklady

Kompletní ukázky několika scénářů šampionů najdete ve samples/ složce.

Klíčové koncepty

Další informace o projektu OpenTelemetry najdete v části Specifikace OpenTelemetry.

Registr modulů plug-in

Pokud chcete zjistit, jestli už není vytvořený modul plug-in pro knihovnu, kterou používáte, projděte si registr OpenTelemetry.

Pokud nemůžete knihovnu v registru použít, můžete navrhnout nový požadavek na modul plug-in na adrese opentelemetry-js-contrib.

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si prosím průvodce přispívání , kde se dozvíte více o tom, jak sestavit a otestovat kód.

Imprese

Sdílet prostřednictvím