從 Application Insights Classic API SDK 遷移到 Azure Monitor OpenTelemetry

本指南提供逐步指引，教你如何將應用程式從使用 Application Insights SDK（Classic API）遷移到 Azure Monitor OpenTelemetry。

預期使用 Azure Monitor OpenTelemetry 的工具體驗將與使用 Application Insights SDK 的體驗相似。欲了解更多資訊及逐項功能比較，請參閱功能發布狀態。

使用 Application Insights .NET 軟體開發套件（SDK）3.x，從 Application Insights .NET SDK 2.x 升級為基於 OpenTelemetry（OTel）的實作。 3.x SDK 保留大部分TelemetryClientTelemetryConfiguration應用程式介面（API），並使用 Azure Monitor OpenTelemetry 匯出器將遙測資料傳送給 Application Insights。

如果你正在建立新應用程式，或已經在使用 Azure Monitor OpenTelemetry 發行版，建議改用 Azure Monitor OpenTelemetry 發行版。不要在同一個應用程式中使用 Application Insights .NET SDK 3.x 和 Azure Monitor 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 用於 Worker Service 與控制台應用程式
Microsoft.ApplicationInsights.Web 用於 .NET Framework 上的 ASP.NET 應用程式
Microsoft.ApplicationInsights.NLogTarget 用於 NLog 整合（beta）

請參考資料庫文件以查看程式碼範例及 OpenTelemetry 整合細節：

升級到 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 套件。

步驟 2：將套件版本升級到 3.x

將所有剩餘支援的 Application Insights 套件升級至最新版本 3.x。

這很重要

不要在同一個應用程式裡混用 Application Insights 2.x 和 3.x 套件。將所有的 Application Insights 套件引用同時升級。

步驟 3：更新程式碼與設定以應對破壞性變更

檢視破壞性變更的參考資料，移除或替換不再支援的 API 與設定。

重大變更：Application Insights 2.x 至 3.x

最常見的變更包括：

刪除 TrackPageView 呼叫。
更新 Track* 呼叫以移除自訂的度量參數。
使用完整連接串 TelemetryConfiguration.ConnectionString替換儀表鍵配置。
以 OpenTelemetry 處理器、儀器函式庫及資源偵測器取代 TelemetryModule、TelemetryInitializer、TelemetryProcessor 的自訂功能。該 ApplicationInsightsServiceOptions 類別包含 EnableQuickPulseMetricStream、 EnablePerformanceCounterCollectionModule、 EnableDependencyTrackingTelemetryModule和 EnableRequestTrackingTelemetryModule。這些 ApplicationInsightsServiceOptions 設定是用來設定匯出器的行為，並不會使用 TelemetryModule 實作。
將自適應抽樣（EnableAdaptiveSampling）替換為 TracesPerSecond 或 SamplingRatio。
請將使用 Microsoft.ApplicationInsights.Web 的 ASP.NET 應用程式鎖定為 .NET Framework 4.6.2 或更新版本。

替換已移除的可擴展點

Application Insights .NET SDK 2.x 提供針對 Application Insights 的可擴充類型，如遙測模組、初始化器與處理器。 Application Insights .NET SDK 3.x 則使用 OpenTelemetry 擴充性。

使用 OpenTelemetry 的儀器與設定選項來控制自動收集。
使用 OpenTelemetry 處理器來豐富或過濾遙測數據。

SDK 3.x 只保留部分 TelemetryContext 屬性。你可以在個別遙測項目上設定以下屬性：

上下文	屬性
`User`	`Id`、`AuthenticatedUserId`、`UserAgent`
`Operation`	`Name`
`Location`	`Ip`
`GlobalProperties`	（字典）

設定取樣

Application Insights .NET SDK 3.x 支援兩種追蹤取樣模式（請求與依賴）：

設定 SamplingRatio 為百分比抽樣的範圍（0.0 到 1.0）。
設定 TracesPerSecond 為速率限制取樣（預設：每秒五次追蹤）。

SDK 3.x 對請求和相依性套用相同的取樣設定。 SDK 3.x 不支援針對請求和依賴的獨立取樣設定。

當請求或相依性被取樣時，SDK 3.x 預設會將父追蹤的取樣決策套用到相關日誌。要停用該行為，請設 EnableTraceBasedLogsSampler 為 false。

你可以在 SamplingRatio、TracesPerSecond 或 EnableTraceBasedLogsSampler 中設定 TelemetryConfiguration、appsettings.json 和 applicationinsights.config。

疑難排解升級

在升級到 SDK 3.x 期間，請使用以下步驟驗證遙測數據：

收集 Application Insights 自我診斷日誌，以識別設定錯誤與匯出器故障。
新增 OpenTelemetry 主控台匯出器，在您依賴 Azure 監視器內嵌之前，先驗證追蹤、指標與記錄是否如預期發出。
透過驗證父子追蹤決策，確認抽樣設定是否如預期運作。
驗證資源屬性，如服務名稱、角色名稱及環境，以確保應用程式洞察中的正確歸因。

如需詳細的故障排除指引與範例，請參考以下資源：

升級到 3.x 通常不會有程式碼變更。 3.x SDK 的相依項目是 2.x SDK 的 no-op API 版本。然而，當與 3.x Java 代理程式一起使用時，3.x Java 代理程式會為它們提供實作。因此，你的自訂儀器會與 3.x Java 代理程式所提供的全新自動儀器相關聯。

步驟 1：更新相依關係

2.x 相依性	動作	備註
`applicationinsights-core`	更新版本至 `3.4.3` 或更高的版本
`applicationinsights-web`	更新版本至`3.4.3`或更高版本，並移除`web.xml`檔案中的 Application Insights 網頁過濾器。
`applicationinsights-web-auto`	替換為`3.4.3`或更高版本的`applicationinsights-web`
`applicationinsights-logging-log4j1_2`	移除相依性，並將 Application Insights 附加器從 Log4j 設定中移除。	由於 Log4j 1.2 已在 3.x Java 代理程式中自動進行儀器化，因此不再需要。
`applicationinsights-logging-log4j2`	移除相依性，並將 Application Insights 附加器從 Log4j 設定中移除。	由於 Log4j 2 在 3.x Java 代理中已被自動安裝，因此不再需要。
`applicationinsights-logging-logback`	移除相依性，並將 Application Insights 附加器從你的 Logback 設定中移除。	由於 Logback 已在 3.x Java 代理程式經過自動檢測，您不再需要採取動作。
`applicationinsights-spring-boot-starter`	替換為`3.4.3`或更高版本的`applicationinsights-web`	雲端角色名稱不再預設為 `spring.application.name`。想了解如何設定雲端角色名稱，請參閱 3.x 的設定文件。

步驟 2：新增 3.x Java 代理程式

例如，將 3.x Java 代理程式加入你的 Java 虛擬機（JVM）命令列參數：

-javaagent:path/to/applicationinsights-agent-3.7.5.jar

如果你用的是 Application Insights 2.x Java 代理程式，只要把現有 -javaagent:... 的代理檔換成前面的範例就好。

備註

如果你使用 applicationinsights-spring-boot-starter，可以用 Spring Boot 整合來取代 Java 代理。如需指引，請參考 3.x Spring Boot。

步驟 3：設定您的 Application Insights 連線字串

請參考設定連線字串。

其他注意事項

本文其餘部分描述了從 2.x 升級到 3.x 時可能遇到的限制與變更，以及一些有用的變通方法。

遙測初始化器

2.x SDK 的 TelemetryInitializers 在使用 3.x 代理時無法執行。許多過去需要撰寫的 TelemetryInitializer 使用案例，可以透過配置自訂維度或使用繼承屬性，在 Application Insights Java 3.x 中解決。

TelemetryProcessors

使用 3.x 代理時，2.x SDK 的 TelemetryProcessors 無法運行。許多過去需要撰寫 TelemetryProcessor 的使用案例，現在可在 Application Insights Java 3.x 藉由設定取樣覆寫來解決。

單一 JVM 中的多個應用程式

此使用情境在 Application Insights Java 3.x 中支援，透過 Cloud 角色名稱覆寫（預覽）及/或連線字串覆寫（預覽）來實現。

作業名稱

在 Application Insights Java 2.x SDK 中，在某些情況下，操作名稱包含完整路徑，例如：

截圖顯示操作名稱及完整路徑

Application Insights Java 3.x 中的操作名稱已更改，以提供 Application Insights 入口網站 U/X 中更佳的彙整視圖，例如：

截圖顯示操作名稱已參數化

不過，對於某些應用，你可能仍偏好先前操作名稱所提供的 U/X 聚合視圖。在這種情況下，你可以使用 3.x 的遙測處理器（預覽）功能來複製之前的行為。

以下片段配置三個遙測處理器，結合以複製先前的行為。遙測處理器依序執行以下動作：

第一個遙測處理器是屬性處理器（屬性 attribute為），意即適用於所有具有屬性（目前 requests 和 dependencies，但很快也有 traces）的遙測。

它匹配任何具有名為http.request.method 和 url.path的屬性的遙測資料。

接著它會將 url.path 屬性擷取成一個新的屬性，名為 tempName。
第二個遙測處理器是區間處理器（型別 span為），意即它適用於 requests 和 dependencies。

它匹配任何帶有屬性為 tempPath的跨度。

接著它會從屬性 tempPath中更新 span 名稱。
最後一個遙測處理器是屬性處理器，與第一個遙測處理器類型相同。

它與任何帶有屬性為 tempPath的遙測資料相符。

接著它會刪除名為 tempPath的屬性，該屬性會以自訂維度的形式出現。

{
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.request.method" },
            { "key": "url.path" }
          ]
        },
        "actions": [
          {
            "key": "url.path",
            "pattern": "https?://[^/]+(?<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 代理開始預設啟用速率限制取樣，可能導致意外的日誌遺失。

專案範例

這個 Java 2.x SDK 專案已透過 3.x Java 代理轉移到新專案。

本指南提供兩種從 Application Insights Node.js SDK 2.X 升級至 OpenTelemetry 的選項。

全新安裝Node.js Azure 監視器 OpenTelemetry 發行版本。
- 移除對 Application Insights 傳統 API 的相依性。
- 熟悉 OpenTelemetry API 和術語。
- 將自己定位為使用 OpenTelemetry 現在和未來提供的所有功能。
升級至 Node.js SDK 3.X。
- 延後程式碼變更，同時保留與現有自訂事件和計量的相容性。
- 存取更豐富的 OpenTelemetry 檢測程式庫。
- 維護最新錯誤和安全性修正的資格。

備註

針對 Azure 函數應用，請參閱在 Azure 函數中使用 OpenTelemetry。

全新安裝

取得 OpenTelemetry JavaScript 應用程式開發介面 (API) 和軟體開發工具套件 (SDK) 的必要條件知識。
- 閱讀 OpenTelemetry JavaScript 文件。
- 檢閱設定 Azure 監視器 OpenTelemetry。
- 評估新增、修改和篩選 OpenTelemetry。
從您的專案解除安裝 applicationinsights 相依性。
```
npm uninstall applicationinsights
```
從程式碼中移除 SDK 2.X 實作。

從您的程式碼移除所有的 Application Insights 檢測設備。刪除 Application Insights 用戶端初始化、修改或呼叫的任何區段。
使用 Azure 監視器 OpenTelemetry 發行版本啟用 Application Insights。

這很重要

在您匯入任何其他專案之前，您必須先呼叫。如果先匯入其他程式庫，可能會遺失遙測資料。請遵循開始使用以上線至 Azure 監視器 OpenTelemetry 發行版本。

Azure 監視器 OpenTelemetry 散發版本變更和限制

Application Insights SDK 2.X 的 API 無法在 Azure 監視器 OpenTelemetry 發行版本中使用。雖然 Application Insights SDK 3.X 提供了不中斷的遙測資料導入升級路徑（如自訂事件與指標），但大多數 SDK 2.X API 不支援，且需修改基於 OpenTelemetry 的 API 程式碼。
目前尚不支援依操作名稱過濾相依性、日誌記錄和例外情況。

升級

升級 applicationinsights 套件相依性。
```
npm update applicationinsights
```
重建應用程式。
測試您的應用程式。

若要避免在 Application Insights SDK 3.X 中使用不支援的設定選項，請參閱不支援的屬性。

如果 SDK 在主要版本更動之後記錄有關不支援 API 使用量的警告，而且您需要相關的功能，請繼續使用 Application Insights SDK 2.X。

變更和限制

下列變更和限制適用於這兩個升級路徑。

Node.js 版本支援

Application Insights 3.x SDK 支援 Node.js 版本，而 Azure SDK for JavaScript 與 OpenTelemetry 皆支援該 Node.js 版本。請前往OpenTelemetry 目前支援的執行時了解更多資訊。

如果你使用較舊的 Node.js 版本，例如 Node 8，OpenTelemetry 解決方案可以執行，但可能會產生意外行為或破壞性變更。 Application Insights SDK 依賴 Azure SDK for JavaScript，而 Azure SDK for JavaScript 支援政策並不保證支援已終止的 Node.js 版本。詳情請前往 Azure SDK for JS 支援政策。

設定選項

Application Insights SDK 2.X 版提供的設定選項，無法在 Azure 監控 OpenTelemetry 發行版本中使用，也無法在升級至 Application Insights SDK 3.X 主要版本時使用。若要尋找這些變更，以及我們仍支援的選項，請參閱 SDK 設定文件。

擴展指標

Application Insights SDK 2.X 支援擴充計量；不過，這些計量的支援會在 ApplicationInsights SDK 3.X 版和 Azure 監視器 OpenTelemetry 發行套件中停止。

遙測處理器

雖然 Azure 監視器 OpenTelemetry 發行版本和 Application Insights SDK 3.X 不支援 TelemetryProcessors，但它們確實可讓您傳遞範圍並記錄記錄處理器。如需詳細資訊，請參閱 Azure 監視器 OpenTelemetry 發行版本專案。

此範例示範如何建立並應用遙測處理器，以將自訂屬性附加到 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 監視器 OpenTelemetry 發行版本實作，以將 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);

備註

針對 Azure 函數應用，請參閱在 Azure 函數中使用 OpenTelemetry。

OpenCensus Python SDK 已淘汰。

請依照以下步驟將 Python 應用程式遷移至 Azure Monitor OpenTelemetry 發行版。

警告

OpenCensus 的「如何遷移到 OpenTelemetry」部落格不適用於 Azure Monitor 使用者。
Microsoft 不推薦也不支援 OpenTelemetry OpenCensus shim。
下列概述 Azure 監視器客戶的唯一移轉方案。

步驟 1：解除安裝 OpenCensus 程式庫

解除安裝與 OpenCensus 相關的所有程式庫，包含 opencensus-* 開頭的所有 Pypi 套件。

pip freeze | grep opencensus | xargs pip uninstall -y

步驟 2：從程式碼移除 OpenCensus

從程式碼移除所有 OpenCensus SDK 和 Azure 監視器匯出工具的執行個體。

檢查以 opencensus 開頭的匯入陳述式，以找出所有必須移除的 OpenCensus API/SDK 整合、匯出者和實例。

以下是必須移除的匯入陳述式範例。

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 APIs/SDK

下列文件提供 OpenTelemetry Python APIs/SDK 的必要條件知識。

OpenTelemetry Python 文檔
Azure Monitor 發行版的設定和遙測文件

備註

OpenTelemetry Python 和 OpenCensus Python 有不同的 API 介面、自動收集功能和上線指示。

步驟 4：設定 Azure 監視器 OpenTelemetry 發行版本

請遵循開始使用頁面以上線至 Azure 監視器 OpenTelemetry 發行版本。

變更和限制

從 OpenCensus 遷移到 OpenTelemetry 時可能會遇到以下變更與限制。

3.7 之前的 Python 版本

基於 OpenTelemetry 的 Python 監控支援 Python 3.7 及更新版本。 OpenTelemetry 不支援 Python 2.7、3.4、3.5 或 3.6。

Python 2.7、3.4、3.5 和 3.6 已經是終止支援版本。想要版本狀態，請前往 Python 版本支援頁面。

如果你繼續使用 Python 2.7、3.4、3.5 或 3.6，OpenTelemetry 解決方案可以執行，但可能會產生 Microsoft 不支援的意外行為或破壞性變更。

對於 OpenCensus，最後釋出的 opencensus-ext-azure 版本運行於這些 Python 版本上。這個專案不會發行新作品。

組態

OpenCensus Python 提供一些與收集和匯出遙測相關的設定選項。您可以使用 OpenTelemetry Python API 和 SDK 來達成相同的設定。 OpenTelemetry Azure 監視器 Python 發行版本是一站式服務，適用於 Python 應用程式最常見監視需求。由於 Distro 封裝了 OpenTelemetry API 與 SDK，目前可能不支援某些較不常見使用案例所需的部分組態。您可改為選擇上線至 Azure 監視器 OpenTelemetry 匯出工具，其中包含 OpenTelemetry API/SDK，應能夠符合監視需求。其中一些設定包含：

自訂傳播器
自訂取樣器
新增額外的跨度/記錄處理器/計量讀取器

與 Azure Functions 的連結

為了提供提供 Python 應用程式的分散式追蹤功能以在 Azure 函式中呼叫其他 Python 應用程式，已提供 opencensus-extension-azure-functions 套件以允許連線的分散式圖表。

目前 Azure 監視器的 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):
  functions_current_context = {
    "traceparent": context.trace_context.Traceparent,
    "tracestate": context.trace_context.Tracestate
  }
  parent_context = TraceContextTextMapPropagator().extract(
      carrier=functions_current_context
  )
  token = attach(parent_context)

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

延伸模組和匯出器

OpenCensus SDK 提供整合以收集遙測資料及匯出器以傳送遙測資料。在 OpenTelemetry 中，整合稱為儀器。 OpenTelemetry 也使用「匯出器」這個詞。

OpenTelemetry Python 的儀器與匯出器涵蓋 OpenCensus 集合，並新增更多函式庫。 OpenTelemetry 直接升級了函式庫的覆蓋範圍與功能。

Azure Monitor OpenTelemetry 發行版包含數個流行的 OpenTelemetry Python 工具。使用這些儀器時，不用加程式碼。 Microsoft 支援這些儀器。

至於未包含在此清單中的其他 OpenTelemetry Python 檢測套件，使用者仍然可以手動使用它們進行檢測。然而，請務必注意，在這些情況下，無法保證或支援穩定性和行為。因此，請自行判斷是否要使用。

如果您想要向我們建議社群檢測程式庫以包含在發行版本，請在意見反應社群中張貼或贊同想法。針對輸出工具，Azure 監視器 OpenTelemetry 發行版本隨附於 Azure 監視器 OpenTelemetry 匯出工具。如果您也想要使用其他匯出工具，您可以搭配發行版一同使用，如這個範例。

TelemetryProcessors

OpenTelemetry 沒有 TelemetryProcessors 的概念，但您可使用 API 和類別來複寫相同的行為。

設定雲端角色名稱和雲端角色執行個體

請遵循這裡的指示，了解如何設定遙測的雲端角色名稱和雲端角色執行個體。 OpenTelemetry Azure 監視器發行版本會自動從環境變數擷取值並填入個別欄位。

使用 SpanProcessors 修改跨度

即將推出。

使用 Views 修改計量

即將推出。

效能計數器

OpenCensus Python Azure 監視器匯出工具會自動收集系統與效能相關的計量，稱為效能計數器。這些計量會顯示在 Application Insights 執行個體的 performanceCounters 中。在 OpenTelemetry 中，我們不再明確將這些計量傳送至 performanceCounters。與傳入/傳出要求相關的計量可在標準計量下找到。如果您要 OpenTelemetry 自動收集系統相關計量，您可使用 OpenTelemetry Python 社群參與的實驗系統計量檢測。此套件是實驗性質，Microsoft 並未正式支援。

Support

若要檢閱疑難解答步驟、支援選項或提供 OpenTelemetry 意見反應，請參閱 Azure 監視器 Application Insights 的 OpenTelemetry 疑難解答、支持和意見反應。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-03-06