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

Статья
09/13/2024

В этом руководстве представлено два варианта обновления с 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.
- Сохраняйте право на наличие последних исправлений ошибок и безопасности.

Очистка установки
Восстановить

Получите необходимые знания о интерфейсе программирования приложений JavaScript OpenTelemetry (API) и пакете средств разработки программного обеспечения (SDK).
- Ознакомьтесь с документацией по OpenTelemetry JavaScript.
- Проверьте настройку Azure Monitor OpenTelemetry.
- Оценка добавления, изменения и фильтрации OpenTelemetry.
applicationinsights Удалите зависимость из проекта.
```
npm uninstall applicationinsights
```
Удалите реализацию ПАКЕТА SDK 2.X из кода.

Удалите все инструментирование Application Insights из кода. Удалите все разделы, в которых клиент Application Insights инициализируется, изменяется или вызывается.
Включите 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.
Фильтрация зависимостей, журналов и исключений по имени операции еще не поддерживается.

applicationinsights Обновите зависимость пакета.
```
npm update applicationinsights
```
Перестройте приложение.
Протестируйте приложение.

Чтобы избежать использования неподдерживаемых параметров конфигурации в пакете SDK для Application Insights 3.X, см. раздел "Неподдерживаемые свойства".

Если пакет SDK регистрирует предупреждения об неподдерживаемом использовании API после удара основной версии, и вам нужна связанная функция, продолжайте использовать пакет SDK Application Insights 2.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);

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