Azure Monitor OpenTelemetry для JavaScript

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

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

npm install @azure/monitor-opentelemetry

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

• Версии Node.js LTS

• Поддерживаемые среды выполнения OpenTelemetry

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

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

Предпосылки

• Подписка Azure
• Рабочая область Application Insights

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

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

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

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

• Строка подключения может быть задана с помощью переменной APPLICATIONINSIGHTS_CONNECTION_STRINGокружения .

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

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

const resource = resourceFromAttributes({ 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);

{
  http: { enabled: true },
  azureSdk: { enabled: false },
  mongoDb: { enabled: false },
  mySql: { enabled: false },
  postgreSql: { enabled: false },
  redis: { enabled: false },
  bunyan: { enabled: false }, 
  winston: { enabled: false } 
}
      

        
{ 
  enabled: false, 
  connectionString: "" 
}
        
      

Параметры могут быть установлены с помощью конфигурационного файла 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"] = "path/to/customConfig.json";

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

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

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

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

• HTTP/HTTPS
• MongoDB
• MySQL
• Postgres
• Редис
• Редис-4
• Azure SDK

Метрики

• HTTP/HTTPS

Записи

• Баньян

• Уинстон

Другие инструментария OpenTelemetry доступны здесь и могут быть добавлены с помощью TracerProvider в AzureMonitorOpenTelemetryClient.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { trace, metrics } from "@opentelemetry/api";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

useAzureMonitor();
registerInstrumentations({
  tracerProvider: trace.getTracerProvider(),
  meterProvider: metrics.getMeterProvider(),
  instrumentations: [new ExpressInstrumentation()],
});

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

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

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

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

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

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

import {
  ATTR_SERVICE_NAME,
  SEMRESATTRS_SERVICE_NAMESPACE,
  SEMRESATTRS_SERVICE_INSTANCE_ID,
} from "@opentelemetry/semantic-conventions";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const customResource = Resource.EMPTY;
customResource.attributes[ATTR_SERVICE_NAME] = "my-helloworld-service";
customResource.attributes[SEMRESATTRS_SERVICE_NAMESPACE] = "my-namespace";
customResource.attributes[SEMRESATTRS_SERVICE_INSTANCE_ID] = "my-instance";

const options: AzureMonitorOpenTelemetryOptions = { resource: customResource };
useAzureMonitor(options);

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

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

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

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

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

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

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

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

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

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

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

import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { Span } from "@opentelemetry/api";
import { SEMATTRS_HTTP_CLIENT_IP } from "@opentelemetry/semantic-conventions";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onStart(_span: Span): void {}
  onEnd(span: ReadableSpan): void {
    span.attributes["CustomDimension1"] = "value1";
    span.attributes["CustomDimension2"] = "value2";
    span.attributes[SEMATTRS_HTTP_CLIENT_IP] = "<IP Address>";
  }
}

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
  // Add the SpanEnrichingProcessor
  spanProcessors: [new SpanEnrichingProcessor()],
};

useAzureMonitor(options);

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

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

import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { Span, Context, trace } from "@opentelemetry/api";
import { AI_OPERATION_NAME } from "@azure/monitor-opentelemetry-exporter";
import { LogRecordProcessor, LogRecord } from "@opentelemetry/sdk-logs";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  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.setAttribute(AI_OPERATION_NAME, (parentSpan as unknown as ReadableSpan).name);
    }
  }
  onEnd(_span: ReadableSpan): void {}
}

class LogRecordEnrichingProcessor implements LogRecordProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onEmit(_logRecord: LogRecord, _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.
      _logRecord.setAttribute(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 { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
   import { IncomingMessage, RequestOptions } from "node:http";
   import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
   
   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 { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
   import { Span, Context, SpanKind, TraceFlags } from "@opentelemetry/api";
   
   class SpanEnrichingProcessor implements SpanProcessor {
     async forceFlush(): Promise<void> {
       // Force flush code here
     }
     onStart(_span: Span, _parentContext: Context): void {
       // Normal code here
     }
     async shutdown(): Promise<void> {
       // Shutdown code here
     }
     onEnd(span: ReadableSpan): void {
       if (span.kind === SpanKind.INTERNAL) {
         span.spanContext().traceFlags = TraceFlags.NONE;
       }
     }
   }
   

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

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

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

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

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

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

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

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

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { metrics, ObservableResult } from "@opentelemetry/api";

useAzureMonitor();
const meter = metrics.getMeter("testMeter");

const histogram = meter.createHistogram("histogram");
const counter = meter.createCounter("counter");
const gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
  const 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");

const 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";

process.env["APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL"] = "VERBOSE";
process.env["APPLICATIONINSIGHTS_LOG_DESTINATION"] = "file";
process.env["APPLICATIONINSIGHTS_LOGDIR"] = "path/to/logs";

useAzureMonitor();

APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVELПеременная окружения может использоваться для установки желаемого уровня журнала, поддерживая следующие значения: NONE, ERROR, WARN, VERBOSEINFODEBUG, и .ALL

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

Примеры

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

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

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

Реестр плагинов

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

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

Вклад

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