Поделиться через

Azure Monitor OpenTelemetry для JavaScript

  • Статья

Версия NPM

Начало работы

Установка пакета

npm install @azure/monitor-opentelemetry

Поддерживаемые в настоящее время среды

Предупреждение: Этот пакет SDK работает только для Node.js сред. Используйте пакет SDK JavaScript для Application Insights для веб-сценариев и сценариев в браузере.

Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.

Предварительные требования

Включение клиента OpenTelemetry в Azure Monitor

Важно:useAzureMonitor необходимо вызвать перед импортом чего-либо еще. При первом импорте других библиотек может возникнуть потеря телеметрии.

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

const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString:
      process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
  },
}
useAzureMonitor(options);
  • Строка подключения может быть задана с помощью переменной среды APPLICATIONINSIGHTS_CONNECTION_STRING

Конфигурация

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);
Свойство Описание По умолчанию
azureMonitorExporterOptions Конфигурация средства экспорта OpenTelemetry в Azure Monitor. Дополнительные сведения см. здесь
samplingRatio Коэффициент выборки должен принимать значение в диапазоне [0,1]. Значение 1 означает, что все данные будут выборки, а 0 — все данные трассировки. 1
instrumentationOptions Разрешить настройку 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 Разрешить настройку веб-инструментирования. { enabled: false, connectionString: "" }
ресурс Ресурс Opentelemetry. Дополнительные сведения см. здесь
samplingRatio Коэффициент выборки должен принимать значение в диапазоне [0,1]. Значение 1 означает, что все данные будут выборки, а 0 — все данные трассировки. 1
enableLiveMetrics Включение и отключение динамических метрик. false
enableStandardMetrics Включение и отключение стандартных метрик. Да
LogRecordProcessors Массив обработчиков записей журналов для регистрации в глобальном поставщике средства ведения журнала.
spanProcessors Массив процессоров span для регистрации в глобальном поставщике трассировки.

Параметры можно задать с помощью файла applicationinsights.json конфигурации, расположенного в корневой @azure/monitor-opentelemetry папке папки установки пакета, например node_modules/@azure/monitor-opentelemetry. Эти значения конфигурации будут применяться ко всем экземплярам AzureMonitorOpenTelemetryClient.

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

Пользовательский JSON-файл можно предоставить с помощью APPLICATIONINSIGHTS_CONFIGURATION_FILE переменной среды.

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

// Application Insights SDK setup....

Библиотеки инструментирования

В состав Azure Monitor OpenTelemetry входят следующие библиотеки инструментирования OpenTelemetry.

Предупреждение: Библиотеки инструментирования основаны на экспериментальных спецификациях OpenTelemetry. Обязательством корпорации Майкрософт по поддержке предварительной версии является обеспечение того, что следующие библиотеки порождают данные для Azure Monitor Application Insights, но при этом критические изменения или экспериментальное сопоставление будут блокировать некоторые элементы данных.

Распределенная трассировка

Метрики

Журналы

Здесь доступны другие инструменты OpenTelemetry, которые можно добавить с помощью TracerProvider в 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,
});

Загрузчик пакета SDK для браузера Application Insights

Загрузчик пакета SDK для браузера Application Insights позволяет внедрять веб-пакет SDK в ответы сервера узла при выполнении следующих условий:

  • Ответ имеет код 200состояния .
  • Метод ответа — GET.
  • Ответ сервера содержит Conent-Type заголовок HTML.
  • Резон сервера содержит теги и .
  • Ответ не содержит текущих конечных точек CDN веб-инструментирования /backup. (текущие и резервные конечные точки CDN веб-инструментирования)

Настройка имени облачной роли и экземпляра облачной роли

Вы можете задать имя облачной роли и экземпляр облачной роли с помощью атрибутов ресурса 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);

Сведения о стандартных атрибутах для ресурсов см. в статье о соглашениях о семантике для ресурсов.

Изменение телеметрии

В этом разделе описано, как изменить телеметрию.

Добавление атрибутов диапазона

Чтобы добавить атрибуты диапазона, используйте один из следующих двух способов:

Эти атрибуты могут включать в себя добавление пользовательского свойства в данные телеметрии.

Совет: Преимущество использования параметров, предоставляемых библиотеками инструментирования, когда они доступны, заключается в том, что доступен весь контекст. В результате пользователи могут добавить или отфильтровать дополнительные атрибуты. Например, параметр обогащения в библиотеке инструментирования HttpClient предоставляет пользователям доступ к самому httpRequestMessage. Они могут выбрать что-нибудь из него и сохранить его как атрибут.

Добавление настраиваемого свойства в трассировку

Все атрибуты, добавляемые в диапазоны, экспортируются как пользовательские свойства.

Использование пользовательского процессора:

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

Фильтрация данных телеметрии

Отфильтровать телеметрию до выхода из приложения можно следующими способами.

  1. Исключите параметр URL-адреса, предоставленный многими библиотеками инструментария HTTP.

    В следующем примере показано, как исключить определенный URL-адрес из трассировки с помощью библиотеки инструментария 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);

  2. Используйте пользовательский процессор. Для исключения определенных диапазонов из экспорта можно использовать процессор пользовательского диапазона. Чтобы пометить диапазоны как не подлежащие экспорту, задайте для TraceFlag значение DEFAULT. Используйте пример добавления пользовательского свойства, но замените следующие строки кода:

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

Пользовательская телеметрия

В этом разделе объясняется, как собирать пользовательские данные телеметрии из приложения.

Добавление пользовательских метрик

Может потребоваться собирать метрики помимо того, что собирают библиотеки инструментирования.

API OpenTelemetry предлагает шесть "инструментов" метрик для различных сценариев метрик, и при визуализации метрик в метриках Обозреватель необходимо выбрать правильный тип агрегирования. Это требование верно при использовании API метрик OpenTelemetry для отправки метрик и при использовании библиотеки инструментирования.

В следующей таблице показаны рекомендуемые типы агрегирования] для каждого из инструментов метрик OpenTelemetry.

Инструмент OpenTelemetry Тип агрегирования Azure Monitor
Счетчик SUM
Асинхронный счетчик SUM
Гистограмма Average, Sum, Count (Max, Min for Python and Node.js only)
Асинхронный датчик Среднее
UpDownCounter (только Python и Node.js) SUM
Асинхронный UpDownCounter (только Python и Node.js) SUM

Осторожностью: Типы агрегирования, выходящие за рамки показанных в таблице, обычно не имеют смысла.

В спецификации OpenTelemetry описаны инструменты и приведены примеры использования каждого из них.

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

Добавление настраиваемых исключений

Выбор библиотек инструментирования автоматически поддерживает исключения в Application Insights. Однако может потребоваться вручную сообщать об исключениях, помимо отчетов библиотек инструментирования. Например, исключения, перехватываемые кодом, обычно не сообщаются, и вы можете сообщить о них и таким образом привлечь к ним внимание в соответствующих интерфейсах, включая колонку сбоев и сквозное представление транзакций.

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

Устранение неполадок

Самодиагностика

Azure Monitor OpenTelemetry использует средство ведения журнала API OpenTelemetry для внутренних журналов. Чтобы включить его, используйте следующую команду:

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 среды можно использовать для задания требуемого уровня журнала с поддержкой следующих значений: NONE, ERROR, WARN, INFO, DEBUGVERBOSE и ALL.

Журналы можно поместить в локальный файл с помощью APPLICATIONINSIGHTS_LOG_DESTINATION переменной среды, поддерживаемые значения: file и file+console, файл с именем applicationinsights.log будет по умолчанию создан в папке tmp, включая все журналы для /tmp *nix и USERDIR/AppData/Local/Temp для Windows. Каталог журналов можно настроить с помощью APPLICATIONINSIGHTS_LOGDIR переменной среды.

Примеры

Полные примеры нескольких сценариев чемпионов см. в папке samples/ .

Основные понятия

Дополнительные сведения о проекте OpenTelemetry см. в спецификациях OpenTelemetry.

Реестр подключаемых модулей

Чтобы узнать, создан ли подключаемый модуль для используемой библиотеки, проверка из реестра OpenTelemetry.

Если вы не можете использовать библиотеку в реестре, вы можете предложить новый запрос подключаемого модуля по адресу opentelemetry-js-contrib.

Участие

Если вы хотите вносить изменения в эту библиотеку, ознакомьтесь с руководством по внесению изменений, в котором содержатся сведения о создании и тестировании кода.

Просмотры