Миграция из пакета SDK 2.X для Application Insights Node.js в Azure Monitor OpenTelemetry

В этом руководстве представлено два варианта обновления с azure Monitor Application Insights Node.js SDK 2.X до OpenTelemetry.

• Чистая установка дистрибутива Node.js Azure Monitor OpenTelemetry.
  • Удалите зависимости от классического API Application Insights.
  • Ознакомьтесь с API и терминами OpenTelemetry.
  • Позиционируйте себя, чтобы использовать все, что OpenTelemetry предлагает сейчас и в будущем.
• Обновление до Node.js пакета SDK 3.X.
  • Откладывайте изменения кода при сохранении совместимости с существующими пользовательскими событиями и метриками.
  • Доступ к более богатым библиотекам инструментирования OpenTelemetry.
  • Сохраняйте право на наличие последних исправлений ошибок и безопасности.

Изменения и ограничения

Следующие изменения и ограничения применяются к обоим путям обновления.

поддержка версий Node.js

Чтобы версия Node.js поддерживалась пакетом SDK ApplicationInsights 3.X, она должна иметь перекрывающуюся поддержку и пакета SDK Azure, и OpenTelemetry. Проверьте поддерживаемые среды выполнения OpenTelemetry для последних обновлений. Пользователи более ранних версий, таких как Node 8, ранее поддерживаемые пакетом SDK ApplicationInsights, по-прежнему могут использовать решения OpenTelemetry, но могут столкнуться с непредвиденным или критическим поведением. Пакет SDK ApplicationInsights также зависит от пакета SDK Azure для JS, который не гарантирует поддержку любых Node.js версий, которые достигли конца жизни. Ознакомьтесь с политикой поддержки Azure SDK для JS. Чтобы версия Node.js поддерживалась пакетом SDK ApplicationInsights 3.X, она должна иметь перекрывающуюся поддержку и пакета SDK Azure, и OpenTelemetry.

Варианты конфигурации

Пакет SDK Application Insights версии 2.X предлагает параметры конфигурации, которые недоступны в дистрибутиве OpenTelemetry Azure Monitor или в обновлении основной версии до пакета SDK Application Insights 3.X. Чтобы найти эти изменения, а также параметры, которые мы по-прежнему поддерживаем, см . документацию по настройке пакета SDK.

Расширенные метрики

Расширенные метрики поддерживаются в пакете SDK для Application Insights 2.X; Однако поддержка этих метрик заканчивается в обоих версиях 3.X пакета SDK ApplicationInsights и дистрибутиве OpenTelemetry в Azure Monitor.

Обработчики данных телеметрии

Хотя Azure Monitor OpenTelemetry Distro и SDK Application Insights 3.X не поддерживают TelemetryProcessors, они позволяют передавать процессоры span и log record. Дополнительные сведения о том, как это сделать, см. в проекте Azure Monitor OpenTelemetry Distro.

В этом примере показывается процесс создания и применения обработчика телеметрии, который добавляет пользовательское свойство в Application Insights SDK версии 2.X.

const applicationInsights = require("applicationinsights");
applicationInsights.setup("YOUR_CONNECTION_STRING");
applicationInsights.defaultClient.addTelemetryProcessor(addCustomProperty);
applicationInsights.start();

function addCustomProperty(envelope: EnvelopeTelemetry) {
    const data = envelope.data.baseData;
    if (data?.properties) {
        data.properties.customProperty = "Custom Property Value";
    }
    return true;
}

В этом примере показано, как изменить реализацию дистрибутива OpenTelemetry в Azure Monitor, чтобы передать SpanProcessor в конфигурацию дистрибутива.

import { Context, Span} from "@opentelemetry/api";
import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

class SpanEnrichingProcessor implements SpanProcessor {
    forceFlush(): Promise<void> {
        return Promise.resolve();
    }
    onStart(span: Span, parentContext: Context): void {
        return;
    }
    onEnd(span: ReadableSpan): void {
        span.attributes["custom-attribute"] = "custom-value";
    }
    shutdown(): Promise<void> {
        return Promise.resolve();
    }
}

const options = {
    azureMonitorExporterOptions: {
        connectionString: "YOUR_CONNECTION_STRING"
    },
    spanProcessors: [new SpanEnrichingProcessor()],
};
useAzureMonitor(options);