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

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. Дополнительные сведения здесь
выборкаRatio Коэффициент выборки должен принимать значение в диапазоне [0,1], то есть все данные будут выборки, а 0 все данные трассировки будут извлечены. 1
инструментированиеOptions Разрешить настройку инструментирования 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 Разрешить настройку веб-инструментирования. { включено: false, connectionString: "" }
ресурс Ресурс Opentelemetry. Дополнительные сведения здесь
выборкаRatio Коэффициент выборки должен принимать значение в диапазоне [0,1], то есть все данные будут выборки, а 0 все данные трассировки будут извлечены. 1
enableLiveMetrics Включение и отключение динамических метрик. истинный
enableStandardMetrics Включение и отключение стандартных метрик. истинный
logRecordProcessors Массив обработчиков записей журналов для регистрации в поставщике глобального средства ведения журнала.
spanProcessors Массив процессоров диапазона для регистрации в глобальном поставщике трассировки.
enableTraceBasedSamplingForLogs Включите выборку журнала на основе трассировки. ложный

Параметры можно задать с помощью applicationinsights.json файла конфигурации, расположенного в корневой папке папки установки пакета @azure/monitor-opentelemetry, ex: 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....

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

Следующие библиотеки инструментирования OpenTelemetry включены в состав Azure Monitor 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.
  • Ответ сервера содержит заголовок html Conent-Type.
  • Резонировать сервер содержит теги и .
  • Ответ не содержит текущих конечных точек CDN веб-инструментирования /backup. (текущие и резервные конечные точки CDN веб-инструментирования, здесь)

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

Задание имени облачной роли и экземпляра облачной роли

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

Добавление имени операции в трассировки и журналы

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

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

Фильтрация телеметрии

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

  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. Используйте пример пользовательского свойства , но замените следующие строки кода:

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

Настраиваемая телеметрия

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

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

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

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

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

Инструмент OpenTelemetry Тип агрегирования Azure Monitor
Прилавок Сумма
Асинхронный счетчик Сумма
Гистограмма Среднее, сумма, число (максимальное, минимальное значение для Python и только Node.js)
Асинхронный датчик Средний
UpDownCounter (только Python и Node.js) Сумма
Асинхронный upDownCounter (только Python и Node.js) Сумма

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

В спецификации 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, 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);
}

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

Самостоятельная диагностика

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

Способствует

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

впечатлений