Azure Monitor OpenTelemetry for JavaScript

Artykuł
10/26/2024

wersji narzędzia npm

Wprowadzenie

Instalowanie pakietu

npm install @azure/monitor-opentelemetry

Obecnie obsługiwane środowiska

Ostrzeżenie: ten zestaw SDK działa tylko dla środowisk Node.js. Użyj zestawu SDK języka JavaScript usługi Application Insights dla scenariuszy internetowych i przeglądarki.

Aby uzyskać więcej informacji, zobacz nasze zasad pomocy technicznej.

Warunki wstępne

subskrypcji platformy Azure
obszaru roboczego usługi Application Insights

Włączanie klienta OpenTelemetry usługi Azure Monitor

Ważne:useAzureMonitor należy wywołać przed zaimportować inne elementy. Może wystąpić utrata danych telemetrycznych, jeśli inne biblioteki zostaną zaimportowane jako pierwsze.

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

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

Parametry połączenia można ustawić przy użyciu zmiennej środowiskowej APPLICATIONINSIGHTS_CONNECTION_STRING

Konfiguracja

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

Własność	Opis	Domyślny
azureMonitorExporterOptions	Konfiguracja eksportera OpenTelemetry w usłudze Azure Monitor. więcej informacji tutaj
samplingRatio	Współczynnik próbkowania musi przyjmować wartość w zakresie [0,1], 1, co oznacza, że wszystkie dane będą próbkowane, a 0 wszystkie dane śledzenia zostaną próbkowane.	1
instrumentacjaOptions	Zezwalaj na konfigurację instrumentacji OpenTelemetry.	{"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	Zezwalaj na konfigurację instrumentacji sieci Web.	{ włączone: false, connectionString: "" }
zasób	Zasób Opentelemetry. więcej informacji tutaj
samplingRatio	Współczynnik próbkowania musi przyjmować wartość w zakresie [0,1], 1, co oznacza, że wszystkie dane będą próbkowane, a 0 wszystkie dane śledzenia zostaną próbkowane.	1
enableLiveMetrics	Włączanie/wyłączanie metryk na żywo.	prawdziwy
enableStandardMetrics	Włączanie/wyłączanie metryk standardowych.	prawdziwy
logRecordProcessors	Tablica procesorów rekordów dzienników do zarejestrowania się u globalnego dostawcy rejestratora.
spanProcessors	Tablica procesorów rozpiętości do zarejestrowania się u globalnego dostawcy śledzenia.
enableTraceBasedSamplingForLogs	Włącz próbkowanie dzienników na podstawie śladu.	fałszywy

Opcje można ustawić przy użyciu pliku konfiguracji applicationinsights.json znajdującego się w folderze głównym folderu instalacyjnego pakietu @azure/monitor-opentelemetry, np. node_modules/@azure/monitor-opentelemetry. Te wartości konfiguracji zostaną zastosowane do wszystkich wystąpień klasy AzureMonitorOpenTelemetryClient.

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

Niestandardowy plik JSON można udostępnić przy użyciu zmiennej środowiskowej APPLICATIONINSIGHTS_CONFIGURATION_FILE.

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

// Application Insights SDK setup....

Biblioteki instrumentacji

Następujące biblioteki instrumentacji OpenTelemetry są uwzględniane w ramach usługi Azure Monitor OpenTelemetry.

Ostrzeżenie: biblioteki instrumentacji są oparte na eksperymentalnych specyfikacjach bibliotek OpenTelemetry. w wersji zapoznawczej zobowiązanie do pomocy technicznej firmy Microsoft polega na upewnieniu się, że następujące biblioteki emitują dane do usługi Azure Monitor Application Insights, ale istnieje możliwość, że zmiany powodujące niezgodność lub mapowanie eksperymentalne będą blokować niektóre elementy danych.

Śledzenie rozproszone

HTTP/HTTPS
bazy danych MongoDB
MySQL
Postgres
Redis
Redis-4
zestawu Azure SDK

Metryki

HTTP/HTTPS

Dzienniki

Inne instrumentacje OpenTelemetry są dostępne tutaj i można je dodać przy użyciu elementu TracerProvider w programie 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,
});

Moduł ładujący zestawu SDK przeglądarki usługi Application Insights

Moduł ładujący zestawu SDK przeglądarki usługi Application Insights umożliwia wstrzykiwanie zestawu SDK sieci Web do odpowiedzi serwera węzła, gdy spełnione są następujące warunki:

Odpowiedź ma kod stanu 200.
Metoda odpowiedzi jest GET.
Odpowiedź serwera ma nagłówek Conent-Type HTML.
Resonse serwera zawiera tagi i .
Odpowiedź nie zawiera bieżących /kopii zapasowych internetowych punktów końcowych usługi CDN instrumentacji. (bieżące i kopie zapasowe punktów końcowych usługi CDN instrumentacji sieci Web tutaj)

Więcej informacji na temat użycia modułu ładującego zestawu SDK przeglądarki można znaleźć tutaj.

Ustawianie nazwy roli chmury i wystąpienia roli w chmurze

Możesz ustawić nazwę roli chmury i wystąpienie roli chmury za pomocą atrybutów zasobów 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);

Aby uzyskać informacje na temat atrybutów standardowych zasobów, zobacz Konwencje semantyczne zasobów.

Modyfikowanie telemetrii

W tej sekcji opisano sposób modyfikowania danych telemetrycznych.

Dodawanie atrybutów zakresu

Aby dodać atrybuty span, użyj jednego z następujących dwóch sposobów:

Użyj opcji udostępnianych przez biblioteki instrumentacji .
Dodaj niestandardowy procesor span.

Te atrybuty mogą obejmować dodawanie właściwości niestandardowej do telemetrii.

Porada: Zaletą korzystania z opcji udostępnianych przez biblioteki instrumentacji, gdy są dostępne, jest to, że cały kontekst jest dostępny. W związku z tym użytkownicy mogą wybrać opcję dodawania lub filtrowania większej liczby atrybutów. Na przykład opcja wzbogacania w bibliotece instrumentacji HttpClient zapewnia użytkownikom dostęp do samego httpRequestMessage. Mogą wybrać dowolne elementy i zapisać je jako atrybut.

Dodawanie właściwości niestandardowej do śledzenia

Wszystkie atrybuty dodawane do zakresów są eksportowane jako właściwości niestandardowe.

Użyj niestandardowego procesora:

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

Filtrowanie danych telemetrycznych

Aby odfiltrować dane telemetryczne przed opuszczeniem aplikacji, możesz użyć następujących sposobów.

Wyklucz opcję adresu URL udostępnioną przez wiele bibliotek instrumentacji HTTP.

W poniższym przykładzie pokazano, jak wykluczyć określony adres URL z śledzenia przy użyciu biblioteki instrumentacji 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);

Użyj procesora niestandardowego. Można użyć niestandardowego procesora zakresu, aby wykluczyć niektóre zakresy z eksportowanych. Aby oznaczyć zakresy, które nie mają być eksportowane, ustaw TraceFlag na wartość DEFAULT. Użyj przykładu dodaj właściwość niestandardową , ale zastąp następujące wiersze kodu:

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

Telemetria niestandardowa

W tej sekcji opisano sposób zbierania niestandardowych danych telemetrycznych z aplikacji.

Dodawanie metryk niestandardowych

Możesz zebrać metryki wykraczające poza to, co jest zbierane przez biblioteki instrumentacji .

Interfejs API OpenTelemetry oferuje sześć metryk "instrumentów", które obejmują różne scenariusze metryk i podczas wizualizacji metryk w Eksploratorze metryk należy wybrać prawidłowy typ agregacji. To wymaganie jest prawdziwe w przypadku używania interfejsu API metryk OpenTelemetry do wysyłania metryk i używania biblioteki instrumentacji.

W poniższej tabeli przedstawiono zalecane typy agregacji] dla każdego z instrumentów metryk OpenTelemetry.

OpenTelemetry Instrument	Typ agregacji usługi Azure Monitor
Lada	Suma
Licznik asynchroniczny	Suma
Histogram	Average, Sum, Count (Max, Min dla języka Python i tylko Node.js)
Miernik asynchroniczny	Średnia
UpDownCounter (tylko język Python i Node.js)	Suma
Asynchroniczny element UpDownCounter (tylko język Python i Node.js)	Suma

Przestroga: typy agregacji wykraczające poza to, co pokazano w tabeli, zwykle nie ma znaczenia.

Specyfikacja OpenTelemetry opisuje instrumenty i zawiera przykłady użycia każdego 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" });

Dodawanie wyjątków niestandardowych

Wybierz pozycję Biblioteki instrumentacji automatycznie obsługują wyjątki do usługi Application Insights. Można jednak ręcznie zgłaszać wyjątki poza raportem bibliotek instrumentacji. Na przykład wyjątki przechwycone przez kod są nie zwykle nie raportowane i możesz zgłosić je, a tym samym zwrócić uwagę na nie w odpowiednich środowiskach, w tym bloku błędów i widoku transakcji kompleksowej.

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

Rozwiązywanie problemów

Samodzielna diagnostyka

Usługa Azure Monitor OpenTelemetry używa rejestratora interfejsu API OpenTelemetry do dzienników wewnętrznych. Aby ją włączyć, użyj następującego kodu:

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 zmiennej środowiskowej można użyć do ustawienia żądanego poziomu dziennika, obsługując następujące wartości: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE i ALL.

Dzienniki można umieścić w pliku lokalnym przy użyciu zmiennej środowiskowej APPLICATIONINSIGHTS_LOG_DESTINATION, obsługiwane wartości są file i file+console, plik o nazwie applicationinsights.log zostanie domyślnie wygenerowany w folderze tmp, w tym wszystkie dzienniki, /tmp dla *nix i USERDIR/AppData/Local/Temp dla systemu Windows. Katalog dziennika można skonfigurować przy użyciu zmiennej środowiskowej APPLICATIONINSIGHTS_LOGDIR.

Przykłady

Aby zapoznać się z kompletnymi przykładami kilku scenariuszy mistrzów, zobacz folder samples/.

Kluczowe pojęcia

Aby uzyskać więcej informacji na temat projektu OpenTelemetry, zapoznaj się z Specyfikacje OpenTelemetry.

Rejestr wtyczek

Aby sprawdzić, czy wtyczka została już utworzona dla używanej biblioteki, zapoznaj się z rejestrem OpenTelemetry.

Jeśli nie możesz używać biblioteki w rejestrze, możesz zasugerować nowe żądanie wtyczki pod adresem opentelemetry-js-contrib.

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

wrażenia

Udostępnij za pośrednictwem