為 .NET、Node.js、Python 和 Java 應用程式啟用 Azure 監視器 OpenTelemetry
本文說明如何啟用和設定以 OpenTelemetry 為基礎的數據收集,以在 Azure 監視器 Application Insights 中提供體驗。 我們會逐步解說如何安裝「Azure 監視器 OpenTelemetry Distro」。散發版本 會自動收集 應用程式及其相依性的追蹤、計量、記錄和例外狀況。 若要深入瞭解如何使用 OpenTelemetry 收集數據,請參閱 數據收集基本概 念或 OpenTelemetry 常見問題。
OpenTelemetry 發行狀態
OpenTelemetry 供應專案適用於 .NET、Node.js、Python 和 Java 應用程式。
注意
如需依功能發行狀態,請參閱 常見問題。
開始使用
請遵循本節中的步驟,以 OpenTelemetry 檢測您的應用程式。
必要條件
- Azure 訂用帳戶: 免費建立 Azure 訂用帳戶
- Application Insights 資源: 建立 Application Insights 資源
安裝客戶端連結庫
安裝最新的 Azure.Monitor.OpenTelemetry.AspNetCore NuGet 套件:
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
啟用 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();
從 Application Insights 資源複製 連線 字串
提示
如果您還沒有帳戶,現在是建立 Application Insights 資源的絕佳時機。 以下是建議您 建立新的 Application Insights 資源,而不是使用現有的資源。
若要複製唯一 連線 字串:
- 移至 Application Insights 資源的 [概觀] 窗格。
- 尋找您的 連線 ion String。
- 將滑鼠停留在 連接字串 上,然後選取 [複製到剪貼簿] 圖示。
在您的環境中貼上 連線 字串
若要貼上您的 連線 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 (不建議)
如需透過程式代碼設定 連線 String 的範例,請參閱 連線 ion 字串組態。
注意
如果您在多個位置設定 連接字串,我們會遵循下列優先順序:
- 代碼
- 環境變數
- 組態檔
確認數據正在流動
執行您的應用程式,並在 Azure 入口網站 中開啟 Application Insights 資源索引標籤。 可能需要幾分鐘的時間,數據才會顯示在入口網站中。
Application Insights 現在已針對您的應用程式啟用。 下列步驟都是選擇性的,並允許進一步自定義。
重要
如果您有兩個以上的服務向相同的 Application Insights 資源發出遙測,您必須 設定雲端角色名稱 ,才能在應用程式對應上正確表示。
作為使用 Application Insights 檢測的一部分,我們會收集診斷數據並將其傳送給 Microsoft。 此數據可協助我們執行及改善 Application Insights。 若要深入瞭解,請參閱 Azure 應用程式 Insights 中的 Statsbeat。
範例
Azure 監視器 OpenTelemetry 範例應用程式適用於所有支持的語言。
下一步
- 如需新增和修改 Azure 監視器 OpenTelemetry 的詳細資訊,請參閱 新增和修改 Azure 監視器 OpenTelemetry。
- 若要進一步設定 OpenTelemetry 散發版本,請參閱 Azure 監視器 OpenTelemetry 設定。
- 若要檢閱原始程式碼,請參閱 Azure 監視器 AspNetCore GitHub 存放庫。
- 若要安裝 NuGet 套件、檢查更新或檢視版本資訊,請參閱 Azure 監視器 AspNetCore NuGet 套件頁面。
- 若要進一步熟悉 Azure 監視器和 OpenTelemetry,請參閱 Azure 監視器範例應用程式。
- 若要深入了解 OpenTelemetry 和其社群,請參閱 OpenTelemetry .NET 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 的精神,我們設計出開放且可延伸的發行版本。 例如,您可以新增:
- OTLP 匯出工具,並同時傳送至第二個目的地
- 發行版本未包含的其他檢測程式庫
如何測試 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,我們建議使用 OpenTelemetry 發行版本。 這是開始使用的一行程式碼。
針對所有其他 .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 意見反應論壇中提出功能要求。