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

發行項
04/08/2024

本文說明如何啟用和設定以 OpenTelemetry 為基礎的資料收集，以便在 Azure 監視器 Application Insights 中強化體驗。我們會逐步解說如何安裝 Azure 監視器 OpenTelemetry Distro。 Azure 監視器 OpenTelemetry Distro 提供 OpenTelemetry 散發套件，其中包含 Azure 監視器特定功能的支援。散發版本藉由包含 OpenTelemetry 檢測連結庫來收集追蹤、計量、記錄和例外狀況，並允許收集自定義遙測，來啟用自動遙測。您也可以使用散發版本中包含的即時計量功能，從即時、生產中的 Web 應用程式監視和收集更多遙測。如需使用 Azure 監視器 OpenTelemetry Distro 之優點的詳細資訊，請參閱 OpenTelemetry 常見問題中的為何應該使用“Azure 監視器 OpenTelemetry Distro”。

若要深入瞭解如何使用 OpenTelemetry 收集數據，請參閱數據收集基本概念或 OpenTelemetry 常見問題。

OpenTelemetry 發行狀態

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

注意

如需依功能發行狀態，請參閱常見問題。

開始使用

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

必要條件

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

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

安裝用戶端程式庫

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

dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

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

dotnet add package Azure.Monitor.OpenTelemetry.Exporter

安裝這些套件：

@azure/monitor-opentelemetry

npm install @azure/monitor-opentelemetry

本文稍後說明的一些特定案例還使用下列套件：

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

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

pip install azure-monitor-opentelemetry

啟用 Azure 監視器 Application Insights

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

修改您的應用程式

將新增 UseAzureMonitor() 至位於類別 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 OpenTelemetry and configure it to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

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

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

將 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.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/trace#tracerprovider-management
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.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/metrics#meterprovider-management
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter();

// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/logs#logger-management
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter();
    });
});

注意

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

透過組態變更啟用Java自動結構;不需要變更程序代碼。

藉由將新增 -javaagent:"path/to/applicationinsights-agent-3.5.1.jar" 至應用程式的 JVM 自變數，將 Java 虛擬機（JVM）指向 jar 檔案。

提示

取樣預設會以每秒 5 個要求的速度啟用，以協助成本管理。在超出此速率的案例中，可能會遺漏遙測數據。如需修改取樣組態的詳細資訊，請參閱取樣覆寫。

提示

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

提示

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

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

# 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 
# APPLICATIONINSIGHTS_CONNECTION_STRING environment variable.
configure_azure_monitor()

從 Application Insights 資源複製連線字串

提示

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

若要複製唯一連線字串：

移至 Application Insights 資源的 [概觀] 窗格。
尋找您的 連線字串。
暫留在連接字串上，選取「複製到剪貼簿」圖示。

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

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

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

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

APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

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

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

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

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

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

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

注意

如果您在多個位置設定連接字串，我們會遵循下列優先順序：

代碼
環境變數
組態檔

確認資料正在流動

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

[Application Insights 概觀] 索引卷標的螢幕快照，其中已醒目提示伺服器要求和伺服器回應時間。

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

重要

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

在使用 Application Insights 檢測的過程中，我們會收集診斷資料並且傳送給 Microsoft。此資料可協助我們執行及改善 Application Insights。若要深入了解，請參閱在 Azure Application Insights 中的 Statsbeat。

範例

Azure 監視器 OpenTelemetry 範例應用程式適用於所有支持的語言。

ASP.NET Core 範例應用程式

下一步

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

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

常見問題集

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

什麼是 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 的絕佳體驗。此包裝函式也稱為 OpenTelemetry 中的散發套件。

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

相較於原生 OpenTelemetry，從社群使用 Azure 監視器 OpenTelemetry Distro 的一些優點如下：

減少啟用工作
Microsoft 不支援
引進 Azure 特定功能，例如：
- 與傳統 Application Insights SDK 相容的取樣
- Microsoft Entra 驗證
- 離線儲存和自動重試
- Statsbeat
- Application Insights 標準計量
- 偵測資源元數據，以在各種 Azure 環境中自動填入雲端角色名稱和雲端角色實例
- 即時計量

秉持 OpenTelemetry 的精神，我們設計出開放且可延伸的發行版本。例如，您可以新增：

OpenTelemetry 通訊協定（OTLP）匯出工具，並同時傳送至第二個目的地
發行版本未包含的其他檢測程式庫

因為散發版本提供 OpenTelemetry 散發套件，因此 Distro 支援 OpenTelemetry 所支援的任何專案。例如，如果 OpenTelemetry 支援遙測處理器、匯出者或檢測連結庫，您可以新增更多遙測處理器、導出者或檢測連結庫。

注意

散發版本會將取樣器設定為 Application Insights 的自定義固定速率取樣器。您可以將此變更為不同的取樣器，但這樣做可能會停用部分散發版本包含的功能。如需支持取樣器的詳細資訊，請參閱設定 Azure 監視器 OpenTelemetry 的啟用取樣一節。

對於沒有支持的獨立 OpenTelemetry 導出工具的語言，Azure 監視器 OpenTelemetry Distro 是目前唯一支援搭配 Azure 監視器使用 OpenTelemetry 的方式。針對具有支持的獨立 OpenTelemetry 匯出工具的語言，您可以選擇使用 Azure 監視器 OpenTelemetry Distro 或視您的遙測案例而定的適當獨立 OpenTelemetry 導出工具。如需詳細資訊，請參閱何時應該使用 Azure 監視器 OpenTelemetry 導出工具？。

如何測試 Azure 監視器 OpenTelemetry Distro？

請查看 .NET、Java、JavaScript (Node.js) 和 Python 的啟用文件。

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

我們建議您使用 OpenTelemetry Distro，除非您需要只有 Application Insights SDK中的正式支援所提供的功能。

採用 OpenTelemetry 現在可防止稍後移轉。

何時應該使用 Azure 監視器 OpenTelemetry 匯出工具？

針對 ASP.NET Core、Java、Node.js 和 Python，我們建議使用 Azure 監視器 OpenTelemetry Distro。這是開始使用的一行程式碼。

針對所有其他 .NET 案例，包括傳統 ASP.NET、控制台應用程式等，我們建議使用 .NET Azure 監視器 OpenTelemetry 導出工具： Azure.Monitor.OpenTelemetry.Exporter。

如需需要進階設定的更複雜的 Python 遙測案例，建議您使用 Python Azure 監視器 OpenTelemetry 導出工具。

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

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

功能	.NET	Node.js	Python	Java
分散式追蹤	✅	✅	✅	✅
自訂計量	✅	✅	✅	✅
標準計量 (目前受取樣影響的正確性)	✅	✅	✅	✅
固定取樣率	✅	✅	✅	✅
離線儲存和自動重試	✅	✅	✅	✅
例外狀況報告	✅	✅	✅	✅
記錄集合	✅	⚠️	✅	✅
自訂事件	⚠️	⚠️	⚠️	✅
Microsoft Entra 驗證	✅	✅	✅	✅
即時計量	❌	❌	❌	✅
偵測 VM/VMSS 和 App Service 的資源內容	✅	❌	✅	✅
偵測 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 端點與 Azure 監視器，但這種做法並非我們打算測試或支援的做法。

是否可以在生產環境中使用預覽功能？

不建議這樣做。請參閱 Microsoft Azure 預覽專用的使用補充條款。

手動和自動檢測有何不同？

請參閱 OpenTelemetry 概觀。

我可以使用 OpenTelemetry 收集器嗎？

儘管 Microsoft 尚未正式支援以代理程式型方法進行應用程式監視，有些客戶使用 OpenTelemetry 收集器做為代理程式替代方案。同時，開放原始碼社群貢獻了 OpenTelemetry 收集器 Azure 監視器匯出工具，部分客戶目前已使用該工具來將資料傳送至 Azure 監視器 Application Insights。 Microsoft 不支援這項功能。

OpenCensus 和 OpenTelemetry 之間有何差異？

OpenCensus 是 OpenTelemetry 的前身。 Microsoft 協助整合 OpenTracing 和 OpenCensus，以建立 OpenTelemetry，這是世界上的單一可檢視性標準。目前生產環境建議而且適用於 Azure 監視器的 Python SDK 是以 OpenCensus 為基礎。 Microsoft 致力於根據 OpenTelemetry 製作 Azure 監視器。

疑難排解

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

支援

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

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

OpenTelemetry 意見反應

若要提供意見反應：

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