从 Application Insights 经典 API SDK 迁移到 OpenTelemetry

使用 Application Insights .NET软件开发工具包 （SDK） 3.x 从 Application Insights .NET SDK 2.x 升级到基于 OpenTelemetry（OTel）的实现。 3.x SDK 保留大多数 TelemetryClient 和 TelemetryConfiguration 应用程序编程接口（API），并使用 Azure Monitor OpenTelemetry 导出程序将遥测数据发送到 Application Insights。

大多数经典 Track* 调用在升级后继续工作，但它们通过发出 OpenTelemetry 信号的内部映射层进行路由。

以下步骤将 Application Insights .NET SDK 2.x 升级到 3.x。 不要与 Application Insights .NET SDK 3.x 一起初始化 OpenTelemetry 发行版。

Application Insights .NET SDK 3.x 概述

Application Insights .NET SDK 3.x 提供以下 NuGet 包：

• Microsoft.ApplicationInsights 和 TelemetryClient 的 TelemetryConfiguration
• Microsoft.ApplicationInsights.AspNetCore 用于 ASP.NET（Active Server Pages .NET）Core Web应用
• 用于工作服务与控制台应用程序的 Microsoft.ApplicationInsights.WorkerService
• 在 .NET Framework 上的 ASP.NET 应用的 Microsoft.ApplicationInsights.Web
• 用于 NLog 集成的 Microsoft.ApplicationInsights.NLogTarget （测试版）

有关代码示例和详细的迁移指南，请参阅存储库文档：

• ApplicationInsights-dotnet 自述文件
• SDK 概念
• 迁移指南：Application Insights 2.x 到 3.x

升级到 3.x

删除不兼容的包，升级支持的包，并更新代码和配置。

步骤 1：删除对不兼容包的引用

删除这些包，因为它们与 SDK 3.x 不兼容：

• Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel
• Microsoft.ApplicationInsights.DependencyCollector
• Microsoft.ApplicationInsights.EventCounterCollector
• Microsoft.ApplicationInsights.PerfCounterCollector
• Microsoft.ApplicationInsights.WindowsServer
• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.ApplicationInsights.Log4NetAppender
• Microsoft.ApplicationInsights.TraceListener
• Microsoft.ApplicationInsights.DiagnosticSourceListener
• Microsoft.ApplicationInsights.EtwCollector
• Microsoft.ApplicationInsights.EventSourceListener

SDK 3.x 不会发布这些包的 3.x 版本。 请改用 Application Insights .NET SDK 3.x 概述中列出的支持的 3.x 包。 以下部分介绍了这些包的预期替换项。 在某些情况下，该功能内置于支持的 3.x 包中，或由 OpenTelemetry API 替换。

步骤 2：将包版本升级到 3.x

将任何剩余支持的 Application Insights 包升级到最新的 3.x 版本。

步骤 3：更新代码和配置以适应重大更改

请查看重大变更参考文档和详细的迁移指南。 大多数应用程序需要更新以下一个或多个区域中的代码或配置：

• 重大更改：Application Insights 从 2.x 到 3.x
• 迁移指南：Application Insights 2.x 到 3.x

替换被移除的可扩展性点

Application Insights .NET SDK 2.x 提供了特定于 Application Insights 的扩展性类型，例如遥测模块、初始值设定项、处理器和通道。 Application Insights .NET SDK 3.x 改用 OpenTelemetry 扩展性。

有关替换 2.x 扩展点（包括边缘情况）的详细指南，请参阅 迁移指南。

配置采样

Application Insights .NET SDK 3.x 支持两种跟踪采样模式（请求和依赖项）：

• 为基于百分比的采样设置 SamplingRatio （0.0 到 1.0）。
• 将TracesPerSecond设置为限速采样（默认值：每秒 5 个轨迹）。

SDK 3.x 对请求和依赖项应用相同的采样设置。 SDK 3.x 不支持请求和依赖项的单独采样设置。

在请求或依赖项被纳入采样时，SDK 3.x 默认会将父级跟踪的采样决策应用于相关日志。 若要禁用该行为，请设置为 EnableTraceBasedLogsSamplerfalse.

可以在SamplingRatio、TracesPerSecond或EnableTraceBasedLogsSampler中设置TelemetryConfiguration、appsettings.json和applicationinsights.config。

排查升级问题

使用以下步骤在升级到 SDK 3.x 期间验证遥测数据：

• 确认在启动之前配置了完整的连接字符串。 如果在测试中验证遥测数据而不使用实际资源，请使用测试用连接字符串。
• 收集 Application Insights 自我诊断日志，以识别配置错误和导出程序故障。
• 添加 OpenTelemetry 控制台导出程序，以验证跟踪、指标和日志在依赖 Azure Monitor 摄取之前是否按照预期发出。
• 如果之前通过模拟 ITelemetryChannel 对遥测进行了单元测试，请切换到适用于 OpenTelemetry 的验证，例如内存中导出程序或用于非生产环境的测试导出程序。
• 通过验证父子跟踪决策，确认采样设置的行为符合预期。
• 验证服务名称、角色名称、角色实例和环境等资源属性，以确保在 Application Insights 中正确归属。
• 如果迁移了自定义扩充，请验证属性是否显示在预期位置。 基于资源的映射可能与 2.x 行为不同。

有关详细的故障排除指南和示例，请使用以下资源：

• Application Insights .NET SDK 故障排除
• 排查 Azure Monitor Application Insights 中应用程序遥测缺失的问题
• 排查 Application Insights 中的高数据引入问题

升级到 3.x 时，通常没有任何代码更改。 3.x SDK 依赖项是 2.x SDK 依赖项的无操作（no-op）API 版本。 但是，当与 3.x Java 代理一起使用时，3.x Java 代理会为其提供实现。 因此，自定义检测与 3.x Java 代理提供的新自动检测相关联。

步骤 1：更新依赖项

步骤 2：添加 3.x Java 代理

将 3.x Java 代理添加到Java虚拟机（JVM）命令行参数，例如：

-javaagent:"<AgentDirectory>/applicationinsights-agent-3.7.9.jar"

如果使用 Application Insights 2.x Java 代理，只需将现有的 -javaagent:... 替换为前面的示例。

步骤 3：配置 Application Insights 连接字符串

请参阅 Configure Azure Monitor OpenTelemetry。

其他说明

本文档的其余部分介绍了从 2.x 升级到 3.x 时可能会遇到的限制和更改，以及一些有用的解决方法。

TelemetryInitializers

使用 3.x 代理时，2.x SDK 中的 TelemetryInitializers 不会运行。 可以通过在 Application Insights Java 3.x 中配置 TelemetryInitializer 或使用 继承属性，解决许多以前需要编写 的用例。

TelemetryProcessors

使用 3.x 代理时，2.x SDK 中的 TelemetryProcessors 不会运行。 许多以前需要编写 TelemetryProcessor 的用例可以通过配置采样替代在 Application Insights Java 3.x 中解决。

单个 JVM 中的多个应用程序

在 Application Insights Java 3.x 中，可以使用 云角色名称覆盖（预览版） 和 连接字符串覆盖（预览版） 来支持此用例。

操作名称

在 Application Insights Java 2.x SDK 中，操作名称有时包括完整路径。 例如：

Application Insights 中的操作名称Java 3.x 通常会在 Application Insights 门户 U/X 中提供更好的聚合视图。 例如：

但是，对于某些应用程序，你可能仍然更喜欢前面操作名称提供的 U/X 中的聚合视图。 在这种情况下，请使用 3.x 中的 遥测处理器 （预览版）功能复制以前的行为。

以下代码片段配置三个遥测处理器，这些处理器合并以复制以前的行为。 遥测处理器执行以下作（按顺序）：

1. 第一个遥测处理器是一个属性处理器（类型为 attribute），这意味着它适用于所有具有属性的遥测（当前包括 requests 和 dependencies，并且不久也将包括 traces）。

   它匹配任何具有名为http.request.method和url.path的属性的遥测数据。

   然后将 url.path 属性提取到名为 tempPath 的新属性中。

2. 第二个遥测处理器是范围处理器（具有类型 span），这意味着它适用于 requests 和 dependencies。

   它匹配任何具有属性名为tempPath的区段。

   然后，它将 http.request.method 和 tempPath 组合起来，以设置 span 名称。

3. 最后一个遥测处理器是属性处理器，与第一个遥测处理器的类型相同。

   它与任何具有名为tempPath属性的遥测匹配。

   然后删除名为 tempPath 的属性。 该属性显示为自定义维度。

{
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.request.method" },
            { "key": "url.path" }
          ]
        },
        "actions": [
          {
            "key": "url.path",
            "pattern": "(?<tempPath>/[^?]*)",
            "action": "extract"
          }
        ]
      },
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "name": {
          "fromAttributes": ["http.request.method", "tempPath"],
          "separator": " "
        }
      },
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "actions": [
          { "key": "tempPath", "action": "delete" }
        ]
      }
    ]
  }
}

采样和日志丢失

从版本 3.4 开始，代理默认启用速率限制采样。 这种采样可能会导致日志意外缺失。

Project示例

此 Java 2.x SDK 项目已迁移到使用 3.x Java 代理的新项目。

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

• 全新安装适用于 Node.js 的 Microsoft OpenTelemetry 发行版。

  • 删除 Application Insights 经典 API 上的依赖项。
  • 熟悉 OpenTelemetry API 和术语。
  • 做好准备，以利用 OpenTelemetry 现在和未来提供的所有功能。

• 升级到 Node.js SDK 3.X。

  • 推迟代码更改，同时保持与现有自定义事件和指标的兼容性。
  • 访问更丰富的 OpenTelemetry 检测库。
  • 确保获得最新的安全和漏洞修复资格。

全新安装

1. 获取 OpenTelemetry JavaScript 应用程序编程接口 (API) 和软件开发工具包 (SDK) 的必备知识。

   • 阅读 OpenTelemetry JavaScript 文档。
   • 查看 在 Application Insights 中配置 OpenTelemetry。
   • 评估添加、修改和筛选 OpenTelemetry。

2. 从项目中卸载 applicationinsights 依赖项。

   npm uninstall applicationinsights
   

3. 从代码中删除 SDK 2.X 实现。

   从代码中删除所有 Application Insights 工具。 删除在其中初始化、修改或调用 Application Insights 客户端的所有部分。

4. 使用 Microsoft OpenTelemetry 发行版启用 Application Insights。

   重要

在加载要插桩的库之前调用 useMicrosoftOpenTelemetry() 。 如果这些库首先加载，可能会丢失遥测数据。 对于 ESM 应用程序，请预加载 Microsoft OpenTelemetry 发行版加载程序。

按照入门指南安装@microsoft/opentelemetry并启用 Azure Monitor 导出。

Microsoft OpenTelemetry 发行版更改和限制

• Microsoft OpenTelemetry 发行版不暴露 Application Insights SDK 2.x API。 将 OpenTelemetry API 用于自定义事件、指标和跨度。 如果需要其经典 API 兼容性，请将 Application Insights SDK 3.x 升级路径分开。
• 替换筛选器和其他特定于 SDK 的配置时，请查看 Microsoft OpenTelemetry 发行版的检测和处理器选项。

Upgrade

1. 将 applicationinsights 包依赖项升级到版本 3.x。

   npm install applicationinsights@^3
   

2. 重新生成应用程序。

3. 测试应用程序。

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

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

更改和限制

以下部分将 Microsoft OpenTelemetry 发行版清理安装路径与 Application Insights SDK 升级路径区分开来。

Node.js 版本支持

Node.js 的 Microsoft OpenTelemetry 发行版需要 Node.js 22 或更高版本。 查看其 运行时和启动要求。

Application Insights 3.x SDK 在 Azure SDK for JavaScript 和 OpenTelemetry 都支持某个 Node.js 版本时，也会支持该 Node.js 版本。 有关当前的 OpenTelemetry 运行时支持，请参阅 OpenTelemetry 支持的运行时。

如果使用较旧的 Node.js 版本（如 Node 8），OpenTelemetry 解决方案可以运行，但可能产生意外行为或破坏性更改。 Application Insights SDK 依赖于适用于 JavaScript 的Azure SDK，而 JavaScript 支持策略的Azure SDK不能保证对达到生命周期结束 Node.js 版本的支持。 有关详细信息，请参阅 JS 支持策略Azure SDK。

配置选项

Microsoft OpenTelemetry Distro 使用 MicrosoftOpenTelemetryOptions，而不是 Application Insights SDK 2.x 配置 API。 Azure Monitor 特定的选项嵌套在 azureMonitor 下；资源、采样、插桩和处理器选项处于顶层。 请参阅 Microsoft OpenTelemetry 发行版配置参考。

有关单独的 Application Insights SDK 3.x 升级路径，请查看 SDK 不支持的属性。

扩展指标

Application Insights SDK 2.x 扩展指标配置不会沿用到 Microsoft OpenTelemetry 发行版。 请改为查看发行版的标准指标和性能计数器设置。 对于 Application Insights SDK 3.x 路径，请查看其 不受支持的属性。

遥测处理器

Microsoft OpenTelemetry 发行版使用 OpenTelemetry Span 和日志记录处理器，而不是经典遥测处理器。 将其注册到 spanProcessors 或 logRecordProcessors. 请参阅 Microsoft OpenTelemetry 发行版配置参考。 对于单独的 SDK 3.x 路径，请使用该 SDK 的配置指南。

此示例演示的操作等同于创建并应用一个在 Application Insights SDK 2.X 中附加自定义属性的遥测处理器。

import * as applicationInsights from "applicationinsights";
applicationInsights.setup("<ConnectionString>");
applicationInsights.defaultClient.addTelemetryProcessor(addCustomProperty);
applicationInsights.start();

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

此示例向 Microsoft OpenTelemetry Distro 注册跨度处理器，以在导出之前添加自定义属性。 在运行它之前，设置APPLICATIONINSIGHTS_CONNECTION_STRING。

import { Context, Span } from "@opentelemetry/api";
import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";

// Import the Microsoft OpenTelemetry Distro.
const { useMicrosoftOpenTelemetry } = require("@microsoft/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();
    }
}

// Configure Azure Monitor export and the options used by this sample.
const options = {
    azureMonitor: {
        azureMonitorExporterOptions: {
            connectionString: "<ConnectionString>",
        },
    },
    spanProcessors: [new SpanEnrichingProcessor()],
};

// Initialize the Microsoft OpenTelemetry Distro.
useMicrosoftOpenTelemetry(options);

按照以下步骤将Python应用程序迁移到 Microsoft OpenTelemetry 发行版。

步骤 1：卸载 OpenCensus 库

卸载与 OpenCensus 相关的所有库，包括以开头 opencensus-*的所有 PyPI 包。

pip freeze | grep opencensus | xargs pip uninstall -y

步骤 2：从代码中删除 OpenCensus

从代码中删除 OpenCensus SDK 的所有实例和 Azure Monitor OpenCensus 导出程序。

检查从头 opencensus 开始的导入语句，以查找必须删除的所有 OpenCensus API/SDK 的集成、导出者和实例。

以下示例显示了必须删除的 import 语句。

from opencensus.ext.azure import metrics_exporter
from opencensus.stats import aggregation as aggregation_module
from opencensus.stats import measure as measure_module

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

from opencensus.ext.azure.log_exporter import AzureLogHandler

步骤 3：熟悉 OpenTelemetry Python API 和 SDK

以下文档提供了 OpenTelemetry Python API 和 SDK 的先决条件知识：

• OpenTelemetry Python 文档
• Microsoft有关配置和遥测的 OpenTelemetry 发行版文档。

设置 Microsoft OpenTelemetry Distro

按照 入门 文章安装 microsoft-opentelemetry 并使用 use_microsoft_opentelemetry(enable_azure_monitor=True) 对其进行初始化。 在启动应用程序之前设置APPLICATIONINSIGHTS_CONNECTION_STRING。 如果以前使用 configure_azure_monitor()过，请删除较旧的发行版初始化。

更改和限制

从 OpenCensus 迁移到 OpenTelemetry 时，可能会发生以下更改和限制。

Python 3.10 之前的版本

适用于 Python 的 Microsoft OpenTelemetry 发行组件需要 Python 3.10 或更高版本。 有关先决条件和支持的版本，请参阅 Microsoft OpenTelemetry Distro for Python。

有关Python版本状态和生命周期结束日期，请转到Python版本支持。

如果仍然使用 Python 2.7、3.4、3.5 或 3.6，OpenTelemetry 解决方案虽然可以运行，但可能会产生意外行为或重大变更，而这些是 Microsoft 不支持的。

对于 OpenCensus，opencensus-ext-azure 的上一个已发布版本在这些Python版本上运行。 该项目不会发布新版本。

配置

OpenCensus Python 配置与 Microsoft OpenTelemetry Distro 并非一一对应。 使用其 配置参考 和 OpenTelemetry API。 使用enable_azure_monitor=True显式启用Azure Monitor。 Azure Monitor导出程序设置使用前缀关键字，例如azure_monitor_connection_string和 azure_monitor_exporter_credential。

发行版支持其他 Span 处理器、日志记录处理器和指标读取器。 通过 OTEL_TRACES_SAMPLER 和 OTEL_TRACES_SAMPLER_ARG 配置采样。 对于发行版外部的自定义管道，独立Azure Monitor OpenTelemetry 导出程序保留其现有的包名称和 API。

与Azure Functions的集成

为了为在 Azure Functions 中调用其他 Python 应用程序的 Python 应用程序提供分布式跟踪功能，opencensus-extension-azure-functions 包会创建一个相互关联的分布式跟踪图。

目前，适用于Azure Monitor的 OpenTelemetry 解决方案不支持此方案。 解决方法是，可以在Azure函数应用程序中手动传播跟踪上下文，如以下示例所示。

from opentelemetry.context import attach, detach
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator


# Context parameter is provided for the body of the function
def main(req, context):
    functionsCurrentContext = {
        "traceparent": context.trace_context.Traceparent,
        "tracestate": context.trace_context.Tracestate,
    }
    parentContext = TraceContextTextMapPropagator().extract(
        carrier=functionsCurrentContext
    )
    token = attach(parentContext)

    ...
    # Function logic
    ...
    detach(token)

扩展和导出程序

OpenCensus SDK 提供收集遥测的集成和发送遥测的导出器。 在 OpenTelemetry 中，集成被称为探测工具。 OpenTelemetry 还使用术语出口器。

OpenTelemetry Python检测和导出程序涵盖 OpenCensus 集并添加更多库。 OpenTelemetry 提供库覆盖范围和功能的直接升级。

Microsoft OpenTelemetry 发行版包括 OpenTelemetry Python插桩库。 它会在受支持的库安装到您的应用程序中时对其进行插桩。 查看 Microsoft OpenTelemetry 发行版的插桩列表和默认值。

至于此列表中不包含的其他 OpenTelemetry Python检测，你仍然可以使用它们手动检测。 但是，在这些情况下，无法保证或支持稳定性和行为。 因此，请自行决定使用它们。

如果要建议一个社区检测库以包含在发行版中，请在 反馈社区中发布或向上投票一个想法。 Microsoft OpenTelemetry 发行版包括Azure Monitor导出，还可以通过 OTLP 发送遥测数据。 请参阅 “启用 OTLP 导出程序”。

遥测处理器

OpenTelemetry 世界没有遥测处理器，但它确实具有可用于复制相同行为的 API 和类。

设置云角色名称和云角色实例

若要设置云角色名称和云角色实例，请参阅 OpenTelemetry 配置。 Microsoft OpenTelemetry 发行版读取标准 OpenTelemetry 资源环境变量，其Azure Monitor集成会将资源属性映射到 Application Insights 字段。

使用 SpanProcessors 修改范围

即将推出。

使用视图修改指标

即将推出。

性能计数器

OpenCensus Python Azure Monitor导出程序会自动收集称为性能计数器的系统和性能相关指标。 这些指标显示在 Application Insights 实例的performanceCounters中。 在 OpenTelemetry 中，您不再显式地将这些指标发送到 performanceCounters。 可以在 标准指标下找到与传入和传出请求相关的指标。 如果希望 OpenTelemetry 自动收集系统相关指标，可以使用 OpenTelemetry Python 社区提供的实验系统指标检测。 此包是实验性的，且未获得 Microsoft 的官方支持。

Support

若要查看故障排除步骤、支持选项或提供 OpenTelemetry 反馈，请参阅 OpenTelemetry 故障排除、支持和Azure Monitor Application Insights 的反馈。