Бөлісу құралы:

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

  • Мақала

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

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

  1. Получите необходимые знания о интерфейсе программирования приложений JavaScript OpenTelemetry (API) и пакете средств разработки программного обеспечения (SDK).

  2. applicationinsights Удалите зависимость из проекта.

    npm uninstall applicationinsights

  3. Удалите реализацию ПАКЕТА SDK 2.X из кода.

    Удалите все инструментирование Application Insights из кода. Удалите все разделы, в которых клиент Application Insights инициализируется, изменяется или вызывается.

  4. Включите Application Insights с помощью дистрибутива OpenTelemetry в Azure Monitor.

    Внимание

    Прежде чем импортировать что-либо другое, useAzureMonitor необходимо вызвать. Если сначала импортируются другие библиотеки, может возникнуть потеря телеметрии. Следуйте инструкциям , приступая к подключению к дистрибутиву OpenTelemetry в Azure Monitor.

Изменения и ограничения для дистрибутива OpenTelemetry в Azure Monitor

  • API из пакета SDK 2.X Application Insights недоступны в дистрибутиве OpenTelemetry в Azure Monitor. Эти API можно получить через неразрывный путь обновления в пакете SDK для Application Insights 3.X.
  • Фильтрация зависимостей, журналов и исключений по имени операции еще не поддерживается.

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

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

поддержка версий 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.

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

Хотя дистрибутивы OpenTelemetry и Пакет SDK Для Application Insights для Azure Monitor 3.X не поддерживают telemetryProcessors, они позволяют передавать процессоры диапазонов и записей журналов. Дополнительные сведения о том, как см. в проекте дистрибутива OpenTelemetry в Azure Monitor.

В этом примере показан эквивалент создания и применения обработчика телеметрии, присоединенного к пользовательскому свойству в пакете SDK Application Insights 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);