你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

项目
09/30/2024

本指南提供了用于从 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 和安全修复的访问资格。

全新安装
升级

获取 OpenTelemetry JavaScript 应用程序编程接口 (API) 和软件开发工具包 (SDK) 的必备知识。
- 阅读 OpenTelemetry JavaScript 文档。
- 查看配置 Azure Monitor OpenTelemetry。
- 评估添加、修改和筛选 OpenTelemetry。
从项目中卸载 applicationinsights 依赖项。
```
npm uninstall applicationinsights
```
从代码中删除 SDK 2.X 实现。

从代码中删除所有 Application Insights 检测。删除在其中初始化、修改或调用 Application Insights 客户端的所有部分。
使用 Azure Monitor OpenTelemetry Distro 启用 Application Insights。

重要

在导入任何其他内容之前，必须调用 useAzureMonitor。如果首先导入其他库，则可能会丢失遥测数据。按照入门加入 Azure Monitor OpenTelemetry Distro。

Azure Monitor OpenTelemetry Distro 更改和限制

Application Insights SDK 2.X 中的 API 在 Azure Monitor OpenTelemetry Distro 中不可用。可以通过 Application Insights SDK 3.X 中的非中断性升级路径访问这些 API。
尚不支持按操作名称筛选依赖项、日志和异常。

升级 applicationinsights 包依赖项。
```
npm update applicationinsights
```
重新生成应用程序。
测试应用程序。

若要避免在 Application Insights SDK 3.X 中使用不受支持的配置选项，请参阅不受支持的属性。

如果 SDK 在主版本更改后记录了有关不支持使用 API 的警告，而你需要相关的功能，请继续使用 Application Insights SDK 2.X。

更改和限制

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

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

通过