从 Node.js Application Insights SDK 2.X 迁移到 Azure Monitor OpenTelemetry

本指南提供了用于从 Azure Monitor Application Insights Node.js SDK 2.X 升级到 OpenTelemetry 的两个选项。

• 全新安装 Node.js Azure Monitor OpenTelemetry Distro。
  • 删除 Application Insights 经典 API 的依赖项。
  • 熟悉 OpenTelemetry API 和术语。
  • 熟悉如何使用 OpenTelemetry 现在和将来提供的所有功能。
• 升级到 Node.js SDK 3.X。
  • 推迟代码更改，同时保持与现有自定义事件和指标的兼容性。
  • 访问更丰富的 OpenTelemetry 检测库。
  • 保持最新 bug 和安全修复的访问资格。

更改和限制

以下更改和限制适用于这两条升级路径。

Node.js 版本支持

要使 ApplicationInsights 3.X SDK 支持 Node.js 版本，它必须受到 Azure SDK 和 OpenTelemetry 的重叠支持。 请查看 OpenTelemetry 支持的运行时以获取最新更新。 使用 Node 8 等旧版本（之前受 ApplicationInsights SDK 支持）的用户仍可以使用 OpenTelemetry 解决方案，但可能会遇到意外或中断性的行为。 ApplicationInsights SDK 还依赖于适用于 JS 的 Azure SDK，它不保证支持生命周期已经结束的任何 Node.js 版本。 请参阅适用于 JS 的 Azure SDK 支持策略。 要使 ApplicationInsights 3.X SDK 支持 Node.js 版本，它必须受到 Azure SDK 和 OpenTelemetry 的重叠支持。

配置选项

Application Insights SDK 版本 2.X 提供了在 Azure Monitor OpenTelemetry Distro 或 Application Insights SDK 3.X 主版本升级中不可用的配置选项。 若要查找这些更改以及我们仍然支持的选项，请参阅 SDK 配置文档。

扩展指标

Application Insights SDK 2.X 支持扩展指标；但是，对这些指标的支持将在 ApplicationInsights SDK 3.X 版和 Azure Monitor OpenTelemetry Distro 中结束。

遥测处理器

虽然 Azure Monitor OpenTelemetry Distro 和 Application Insights SDK 3.X 不支持 TelemetryProcessors，但它们确实允许你传递范围和日志记录处理器。 有关操作方法的详细信息，请参阅 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;
}

此示例演示如何修改 Azure Monitor OpenTelemetry Distro 实现，以将 SpanProcessor 传递给 Distro 的配置。

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