為 .NET、Node.js、Python 和 Java 應用程式啟用 Azure 監視器 OpenTelemetry

本文說明如何啟用和設定以 OpenTelemetry 為基礎的數據收集，以在 Azure 監視器 Application Insights 中提供體驗。 我們會逐步解說如何安裝「Azure 監視器 OpenTelemetry Distro」。散發版本 會自動收集 應用程式及其相依性的追蹤、計量、記錄和例外狀況。 若要深入瞭解如何使用 OpenTelemetry 收集數據，請參閱 數據收集基本概 念或 OpenTelemetry 常見問題。

OpenTelemetry 發行狀態

OpenTelemetry 供應專案適用於 .NET、Node.js、Python 和 Java 應用程式。

語言	發行狀態
.NET （匯出者）	✅ ¹
Java	✅ ¹
Node.js	✅ ¹
Python	✅ ¹
ASP.NET Core	⚠️ ²

腳注

• 1 ✅ ：OpenTelemetry 可供所有正式支持的客戶使用。
• ^ ⚠： OpenTelemetry 可作為公開預覽版。 Microsoft Azure Preview 補充使用規定

注意

如需依功能發行狀態，請參閱 常見問題。 ASP.NET Core Distro 在 GA 之前正在進行額外的穩定性測試。 如果您需要 ASP.NET Core 應用程式的完整支援 OpenTelemetry 解決方案，您可以使用 .NET 導出工具。

開始使用

請遵循本節中的步驟，以 OpenTelemetry 檢測您的應用程式。

必要條件

• Azure 訂用帳戶： 免費建立 Azure 訂用帳戶
• Application Insights 資源： 建立 Application Insights 資源

ASP.NET Core

• 使用正式支援的 .NET Core 版本 ASP.NET Core 應用程式

.NET

• 使用至少為 .NET Framework 4.6.2 之 正式支援的 .NET Core 或 .NET Framework 版本的應用程式

Java

• 使用 JAVA 8+ 的 JAVA 應用程式

Node.js

注意

如果您依賴不支援資料表 中的任何 屬性，請使用散發版本，我們很快就會提供移轉指南。 如果沒有，當 App Insights 填充碼不在 Beta 版時，就是您最容易前進的路徑。

• 使用正式 支援的 Node.js 執行時間版本 的應用程式：
  • OpenTelemetry 支援的執行時間
  • Azure 監視器 OpenTelemetry 匯出工具支援的執行時間

Python

• 使用 Python 3.7+ 的 Python 應用程式

提示

不建議搭配 Azure 監視器 OTel 散發版本使用 OTel Community SDK/API，因為它會自動將它們載入為相依性。

安裝用戶端程式庫

ASP.NET Core

安裝最新的 Azure.Monitor.OpenTelemetry.AspNetCore NuGet 套件：

dotnet add package --prerelease Azure.Monitor.OpenTelemetry.AspNetCore 

.NET

安裝最新的 Azure.Monitor.OpenTelemetry.匯出 工具 NuGet 套件：

dotnet add package Azure.Monitor.OpenTelemetry.Exporter 

Java

下載 applicationinsights-agent-3.4.18.jar 檔案。

警告

如果您要從舊版 3.x 升級，可能會因變更預設值或我們所收集的資料稍有差異而受到影響。 如需詳細資訊，請參閱版本資訊中的移轉一節。 3.4.0 、 3.3.0 、 3.2.0 和 3.1.0

Node.js

安裝下列套件：

• @azure/monitor-opentelemetry

npm install @azure/monitor-opentelemetry

下列套件也用於本文稍後所述的一些特定案例：

• @opentelemetry/api
• @opentelemetry/sdk-metrics
• @opentelemetry/資源
• @opentelemetry/semantic-conventions
• @opentelemetry/sdk-trace-base

npm install @opentelemetry/api
npm install @opentelemetry/sdk-metrics
npm install @opentelemetry/resources
npm install @opentelemetry/semantic-conventions
npm install @opentelemetry/sdk-trace-base

Python

安裝最新的 azure-monitor-opentelemetry PyPI 套件：

pip install azure-monitor-opentelemetry

啟用 Azure 監視器 Application Insights

若要啟用 Azure 監視器 Application Insights，您可以稍微修改應用程式，並設定「連線ion String」。連線ion String 會告知您的應用程式要傳送散發版本收集的遙測，而且對您而言是唯一的。

修改您的應用程式

ASP.NET Core

將 新增 UseAzureMonitor() 至您的應用程式啟動。 視您的 .NET 版本而定，它位於 您的 startup.cs 或 program.cs 類別中。

// Import the Azure.Monitor.OpenTelemetry.AspNetCore namespace.
using Azure.Monitor.OpenTelemetry.AspNetCore;

// Create a new WebApplicationBuilder instance.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry NuGet package to the application's services and configure OpenTelemetry to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the application.
var app = builder.Build();

// Run the application.
app.Run();

.NET

將 Azure 監視器匯出工具新增至應用程式啟動時的每個 OpenTelemetry 訊號。 視您的 .NET 版本而定，它位於 您的 startup.cs 或 program.cs 類別中。

// Create a new tracer provider builder and add an Azure Monitor trace exporter to the tracer provider builder.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter();

// Add an Azure Monitor metric exporter to the metrics provider builder.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter();

// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter();
    });
});

注意

如需詳細資訊，請參閱 OpenTelemetry .NET 的快速入門教學課程

Java

透過組態變更啟用 JAVA 自動結構;不需要變更程式碼。

將 JVM 新增 -javaagent:"path/to/applicationinsights-agent-3.4.18.jar" 至應用程式的 JVM 引數，將 JVM 指向 jar 檔案。

提示

如需案例特定的指引，請參閱 開始使用（補充）。

提示

如果您開發 Spring Boot 應用程式，您可以選擇性地以程式設計方式設定取代 JVM 引數。 如需詳細資訊，請參閱 搭配 Spring Boot 使用 Azure 監視器 Application Insights。

Node.js

// Import the `useAzureMonitor()` function from the `@azure/monitor-opentelemetry` package.
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

// Call the `useAzureMonitor()` function to configure OpenTelemetry to use Azure Monitor.
useAzureMonitor();

Python

# Import the `configure_azure_monitor()` function from the
# `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Import the tracing api from the `opentelemetry` package.
from opentelemetry import trace

# Configure OpenTelemetry to use Azure Monitor with the specified connection
# string.
configure_azure_monitor(
    connection_string="<Your Connection String>",
)

# Get a tracer for the current module.
tracer = trace.get_tracer(__name__)

# Start a new span with the name "hello". This also sets this created span as the current span in this context. This span will be exported to Azure Monitor as part of the trace.
with tracer.start_as_current_span("hello"):
    print("Hello, World!")

# Wait for export to take place in the background.
input()

從 Application Insights 資源複製連線字串

提示

如果您還沒有帳戶，現在是建立 Application Insights 資源 的絕佳時機 。 以下是建議您 建立新的 Application Insights 資源，而不是使用現有的 資源。

若要複製唯一的連線字串：

1. 移至 Application Insights 資源的 [ 概觀] 窗格。
2. 尋找您的 連線字串 。
3. 將滑鼠停留在連接字串上，然後選取 [ 複製到剪貼簿 ] 圖示。

在您的環境中貼上連線字串

若要貼上您的連線ion String，請從下列選項中選取：

A. 透過環境變數設定 （建議）

將下列命令中的 取代 <Your Connection String> 為您的 唯一連接字串。

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

B. 透過組態檔設定 - 僅限 JAVA （建議）

建立名為 applicationinsights.json 的組態檔，並將它放在與下列內容相同的目錄中 applicationinsights-agent-3.4.18.jar ：

{
  "connectionString": "<Your Connection String>"
}

將上述 JSON 中的 取代 <Your Connection String> 為您的 唯一連接字串。

C. 透過程式碼設定 - ASP.NET Core、Node.js 和 Python （不建議）

如需透過程式碼設定連線字串的範例，請參閱 連線ion 字串 組態。

注意

如果您在多個位置設定連接字串，我們會遵守下列先行規定：

1. 代碼
2. 環境變數
3. 組態檔

確認資料正在流動

執行您的應用程式，並在Azure 入口網站中開啟 Application Insights 資源 索引標籤。 可能需要幾分鐘的時間，資料才會顯示在入口網站中。

您現在已為應用程式啟用 Application Insights。 下列步驟都是選擇性的，並允許進一步自訂。

重要

如果您有兩個以上的服務向相同的 Application Insights 資源發出遙測，您必須 設定雲端角色名稱 ，才能在應用程式對應上正確表示。

作為使用 Application Insights 檢測的一部分，我們會收集診斷資料並將其傳送給 Microsoft。 此資料可協助我們執行及改善 Application Insights。 若要深入瞭解，請參閱 Azure 應用程式 Insights 中的 Statsbeat。

常見問題集

本節提供常見問題的解答。

什麼是 OpenTelemetry？

這是可觀察性的新開放原始碼標準。 若要深入瞭解，請參閱 OpenTelemetry 。

為什麼 Microsoft Azure 監視器投資 OpenTelemetry？

Microsoft 是 OpenTelemetry 的最大參與者之一。

OpenTelemetry 的主要價值主張是，它是廠商中立的，並跨語言提供一致的 API/SDK。

一段時間後，我們相信 OpenTelemetry 可讓 Azure 監視器客戶觀察以我們支援 的語言以外的 語言撰寫的應用程式。 它也會擴充您可以透過一組 豐富的檢測程式庫 所收集的資料類型。 此外，OpenTelemetry SDK 的規模比其前身 Application Insights SDK 更具效能。

最後，OpenTelemetry 與 Microsoft 採用開放原始碼 的策略 一致。

OpenTelemetry 的狀態為何？

請參閱 OpenTelemetry 規格合規性矩陣。

什麼是「Azure 監視器 OpenTelemetry Distro」？

您可以將它視為精簡包裝函式，將所有 OpenTelemetry 元件組合在一起，以取得 Azure 上一流的體驗。

為何應該使用「Azure 監視器 OpenTelemetry Distro」？

從社群使用 Azure 監視器 OpenTelemetry Distro，比起原生 OpenTelemetry，有幾個優點：

• 減少啟用工作
• Microsoft 支援
• 引進 Azure 特定功能，例如：
  • 使用 Application Insights SDK 保留服務元件的追蹤
  • Microsoft Entra 驗證
  • 離線 儲存體和自動重試
  • Statsbeat
  • Application Insights 標準計量
  • 偵測資源元數據以在 Azure 上自動填入雲端角色名稱
  • 即時計量 （未來）

以OpenTelemetry的精神，我們設計了要開放且可延伸的散發版本。 例如，您可以新增：

• OTLP 導出工具，並同時傳送至第二個目的地
• 套件所配套專案以外的社群檢測連結庫

如何測試 Azure 監視器 OpenTelemetry Distro？

請查看 .NET、Java、JavaScript （Node.js） 和 Python 的啟用檔。

我應該使用 OpenTelemetry 或 Application Insights SDK 嗎？

要看情況而定。 請考慮 Azure 監視器 OpenTelemetry Distro 仍然是「預覽」，而且與 Application Insights SDK 的功能不完全相同。

Azure 監視器 OpenTelemetry Distro 中功能目前的發行狀態為何？

下圖細分了每個語言的 OpenTelemetry 功能支援。

功能	.NET	Node.js	Python	Java
分散式追蹤	⚠️	✅	✅	✅
自訂計量	⚠️	✅	✅	✅
標準計量 （目前受取樣影響的正確性）	⚠️	✅	✅	✅
固定取樣率	⚠️	✅	✅	✅
離線記憶體和自動重試	⚠️	✅	✅	✅
例外狀況報告	⚠️	✅	✅	✅
記錄收集	⚠️	⚠️	✅	✅
自訂事件	⚠️	⚠️	⚠️	✅
Microsoft Entra 驗證	⚠️	✅	✅	✅
即時計量	❌	❌	❌	✅
偵測 VM/VMSS 和應用程式 Svc 的資源內容	✅	❌	✅	✅
偵測 AKS 和函式的資源內容	❌	❌	❌	✅
可用性測試範圍篩選	❌	❌	❌	✅
自動填入使用者標識碼、已驗證的使用者標識碼和使用者IP	❌	❌	❌	✅
手動覆寫/設定作業名稱、使用者標識碼或已驗證的使用者識別碼	❌	❌	❌	✅
調適型取樣	❌	❌	❌	✅
分析工具	❌	❌	❌	⚠️
快照偵錯工具	❌	❌	❌	❌

索引鍵

• ✅ 這項功能適用於所有具有正式支持的客戶。
• ⚠️ 這項功能可作為公開預覽。 請參閱 Microsoft Azure 預覽版的補充使用規定。
• ❌ 此功能無法使用或不適用。

OpenTelemetry 是否可以用於網頁瀏覽器？

是的，但我們不建議使用，Azure 不支援它。 OpenTelemetry JavaScript 已針對 Node.js 進行大量優化。 相反地，我們建議使用Application Insights JavaScript SDK。

何時可以預期 OpenTelemetry SDK 可用於網頁瀏覽器？

尚未判斷 OpenTelemetry Web SDK 的可用性時程表。 我們可能需要幾年的時間，而瀏覽器 SDK 將是 Application Insights JavaScript SDK 的可行替代方案。

我今天可以在網頁瀏覽器中測試 OpenTelemetry 嗎？

OpenTelemetry Web 沙箱是一個分支，其設計目的是讓 OpenTelemetry 在瀏覽器中運作。 尚無法將遙測傳送至 Application Insights。 SDK 目前尚未定義一般用戶端事件。

是否支援與 AppDynamics、DataDog 和 NewRelic 等競爭對手代理程式一起執行 Application Insights？

否。 雖然我們的散發版本可讓您 同時導出至 OTLP 端點 ，但這種做法並非我們打算測試或支援的做法。

我可以在生產環境中使用預覽組建嗎？

我們不建議這麼做。 請參閱 Microsoft Azure 預覽版的補充使用規定。

我可以使用 Azure 監視器匯出工具作為獨立元件嗎？

是的，我們瞭解某些客戶可能想要使用「分次方法」進行檢測。 不過，散發版本提供最簡單的方式，讓您在 Azure 上開始使用最佳體驗。

手動和自動檢測之間的差異為何？

請參閱 OpenTelemetry 概觀。

我可以使用 OpenTelemetry 收集器嗎？

有些客戶已開始使用 OpenTelemetry Collector 做為代理程式替代方案，儘管 Microsoft 尚未正式支援代理程式型方法來監視應用程式。 同時，開放原始碼社群貢獻了 OpenTelemetry Collector Azure Monitor 導出工具 ，有些客戶會使用該導出工具將數據傳送至 Azure 監視器 Application Insights。

我們計劃在未來支援代理程式型方法，但尚未提供詳細數據和時程表。 我們的目標是提供任何 OpenTelemetry 支援的語言路徑，以透過 OpenTelemetry 通訊協定 （OTLP） 傳送至 Azure 監視器。 這種方法可讓客戶觀察以語言撰寫的應用程式，超出我們 支持的語言。

OpenCensus 和 OpenTelemetry 有何差異？

OpenCensus 是 OpenTelemetry 的前身。 Microsoft 協助整合 OpenTracing 和 OpenCensus 來建立 OpenTelemetry，這是世界上的單一可觀察性標準。 目前 生產建議的適用於 Azure 監視器的 Python SDK 是以 OpenCensus 為基礎。 最後，所有 Azure 監視器 SDK 都會以 OpenTelemetry 為基礎。

疑難排解

ASP.NET Core

無法運作？ 請參閱 ASP.NET Core 的疑難解答頁面。

.NET

無法運作？ 請參閱 .NET 的疑難解答頁面。

Java

無法運作？ 請參閱 Java 的疑難解答頁面。

Node.js

無法運作？ 請查看 Node.js 的疑難解答頁面。

Python

無法運作？ 請查看 Python 的疑難解答頁面。

支援

選取您選擇的語言索引標籤，以探索支援選項。

ASP.NET Core

• 針對 Azure 支援 問題，請開啟 Azure 支援 票證。
• 如需 OpenTelemetry 問題，請直接連絡 OpenTelemetry .NET 社群 。
• 如需與 Azure 監視器匯出工具相關的開放問題清單，請參閱 GitHub 問題頁面。

.NET

• 針對 Azure 支援 問題，請開啟 Azure 支援 票證。
• 如需 OpenTelemetry 問題，請直接連絡 OpenTelemetry .NET 社群 。
• 如需與 Azure 監視器匯出工具相關的開放問題清單，請參閱 GitHub 問題頁面。

Java

• 針對 Azure 支援 問題，請開啟 Azure 支援 票證。
• 如需疑難解答的說明，請檢閱 疑難解答步驟。
• 如需 OpenTelemetry 問題，請直接連絡 OpenTelemetry 社群 。
• 如需與 Azure 監視器 Java 自動結構相關的開啟問題清單，請參閱 GitHub 問題頁面。

Node.js

• 針對 Azure 支援 問題，請開啟 Azure 支援 票證。
• 如需 OpenTelemetry 問題，請直接連絡 OpenTelemetry JavaScript 社群 。
• 如需與 Azure 監視器匯出工具相關的開放問題清單，請參閱 GitHub 問題頁面。

Python

• 針對 Azure 支援 問題，請開啟 Azure 支援 票證。
• 如需 OpenTelemetry 問題，請直接連絡 OpenTelemetry Python 社群 。
• 如需與 Azure 監視器散發版本相關的開放問題清單，請參閱 GitHub 問題頁面。

OpenTelemetry 意見反應

若要提供意見反應：

• 填寫 OpenTelemetry 社群的客戶 意見反應問卷。
• 加入 OpenTelemetry 早期採用者社群，告訴 Microsoft 自己。
• 與 Microsoft Tech Community 中的其他 Azure 監視器用戶互動。
• 在 Azure 意見反應論壇提出功能要求。

下一步

ASP.NET Core

• 如需新增和修改 Azure 監視器 OpenTelemetry 的詳細資訊，請參閱 新增和修改 Azure 監視器 OpenTelemetry
• 若要進一步設定 OpenTelemetry 散發版本，請參閱 Azure 監視器 OpenTelemetry 設定
• 若要檢閱原始程式碼，請參閱 Azure 監視器 AspNetCore GitHub 存放庫。
• 若要安裝 NuGet 套件、檢查更新或檢視版本資訊，請參閱 Azure 監視器 AspNetCore NuGet 套件 頁面。
• 若要更熟悉 Azure 監視器和 OpenTelemetry，請參閱 Azure 監視器範例應用程式。
• 若要深入瞭解 OpenTelemetry 及其社群，請參閱 OpenTelemetry .NET GitHub 存放庫。
• 若要啟用使用體驗， 請啟用網頁或瀏覽器用戶監視。

.NET

• 如需新增和修改 Azure 監視器 OpenTelemetry 的詳細資訊，請參閱 新增和修改 Azure 監視器 OpenTelemetry
• 若要進一步設定 OpenTelemetry 散發版本，請參閱 Azure 監視器 OpenTelemetry 設定
• 若要檢閱原始程式碼，請參閱 Azure 監視器匯出工具 GitHub 存放 庫。
• 若要安裝 NuGet 套件、檢查更新或檢視版本資訊，請參閱 Azure 監視器匯出工具 NuGet 套件 頁面。
• 若要更熟悉 Azure 監視器和 OpenTelemetry，請參閱 Azure 監視器範例應用程式。
• 若要深入瞭解 OpenTelemetry 及其社群，請參閱 OpenTelemetry .NET GitHub 存放庫。
• 若要啟用使用體驗， 請啟用網頁或瀏覽器用戶監視。

Java

• 如需新增和修改 Azure 監視器 OpenTelemetry 的詳細資訊，請參閱 新增和修改 Azure 監視器 OpenTelemetry
• 檢閱 Java自動結構設定選項。
• 若要檢閱原始程式碼，請參閱 Azure 監視器 Java 自動結構 GitHub 存放庫。
• 若要深入瞭解 OpenTelemetry 及其社群，請參閱 OpenTelemetry Java GitHub 存放庫。
• 若要啟用使用體驗，請參閱 啟用網頁或瀏覽器用戶監視。
• 請參閱 GitHub 上的版本資訊。

Node.js

• 如需新增和修改 Azure 監視器 OpenTelemetry 的詳細資訊，請參閱 新增和修改 Azure 監視器 OpenTelemetry
• 若要檢閱原始程式碼，請參閱 Azure 監視器 OpenTelemetry GitHub 存放庫。
• 若要安裝 npm 套件並檢查更新，請參閱 @azure/monitor-opentelemetry npm 套件 頁面。
• 若要更熟悉 Azure 監視器 Application Insights 和 OpenTelemetry，請參閱 Azure 監視器範例應用程式。
• 若要深入瞭解 OpenTelemetry 及其社群，請參閱 OpenTelemetry JavaScript GitHub 存放庫。
• 若要啟用使用體驗， 請啟用網頁或瀏覽器用戶監視。

Python

• 如需新增和修改 Azure 監視器 OpenTelemetry 的詳細資訊，請參閱 新增和修改 Azure 監視器 OpenTelemetry
• 若要檢閱原始程式碼和額外檔，請參閱 Azure 監視器散發套件 GitHub 存放庫。
• 若要查看額外的範例和使用案例，請參閱 Azure 監視器散發版本範例。
• 請參閱 GitHub 上的版本資訊。
• 若要安裝 PyPI 套件、檢查更新或檢視版本資訊，請參閱 Azure 監視器散發套件 頁面。
• 若要更熟悉 Azure 監視器 Application Insights 和 OpenTelemetry，請參閱 Azure 監視器範例應用程式。
• 若要深入瞭解 OpenTelemetry 及其社群，請參閱 OpenTelemetry Python GitHub 存放庫。
• 若要查看可用的 OpenTelemetry 檢測和元件，請參閱 OpenTelemetry 參與者 Python GitHub 存放庫。
• 若要啟用使用體驗， 請啟用網頁或瀏覽器用戶監視。