OpenTelemetry 說明、支持和意見反應

本文提供適用於 .NET、Java、Node.js 和 Python 應用程式的 Azure 監視器 Application Insights 上的 OpenTelemetry 說明、支援和意見反應選項。

• 檢閱常見問題
• 採取疑難解答步驟
• 取得支援
• 提供意見反應

常見問題集

什麼是 OpenTelemetry？

適用於可檢視性的新開放原始碼標準。 若要深入了解，請參閱 OpenTelemetry (英文)。

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

Microsoft 投資 OpenTelemetry 的原因如下：

• 它是廠商中立的，且跨語言提供一致的 API/SDK。
• 一段時間後，我們相信 OpenTelemetry 能讓 Azure 監視器客戶觀察使用我們支援語言以外的語言所撰寫的應用程式。
• 這會擴充您可以透過一組多樣化的檢測程式庫所收集的資料類型。
• OpenTelemetry 軟體開發套件 (SDK) 的規模比其前身 Application Insights SDK 更具效能。
• OpenTelemetry 會配合 Microsoft 的策略採用開放原始碼。

OpenTelemetry 的狀態為何？

請參閱 OpenTelemetry 狀態。

什麼是 Azure 監視器 OpenTelemetry 發行版本？

您可以將此視為精簡包裝函式，將全部 OpenTelemetry 元件組合在一起，以獲得 Azure 的絕佳體驗。 此包裝函式也稱為 OpenTelemetry 中的散發。

為何應該使用 Azure 監視器 OpenTelemetry 發行版本？

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

• 減少啟用工作
• 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 發行版本是目前唯一支援搭配 Azure 監視器使用 OpenTelemetry 的方式。 針對具有支援的獨立 OpenTelemetry 匯出工具的語言，您可以選擇使用 Azure 監視器 OpenTelemetry Distro，或視您遙測案例而定的適當獨立 OpenTelemetry 匯出工具。 如需詳細資訊，請參閱何時應該使用 Azure 監視器 OpenTelemetry 匯出工具？。

如何測試 Azure 監視器 OpenTelemetry 發行版本？

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

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

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

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

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

針對 ASP.NET Core、JAVA、Node.js 和 Python，我們建議使用 Azure Monitor OpenTelemetry 發行版本。 這是開始使用的一行程式碼。

針對所有其他 .NET 案例 (包括傳統 ASP.NET、主控台應用程式、Windows Forms (WinForms) 等)，建議使用 .NET Azure 監視器 OpenTelemetry 匯出工具：Azure.Monitor.OpenTelemetry.Exporter。

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

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

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

功能	.NET	Node.js	Python	Java
分散式追蹤	✅	✅	✅	✅
自訂計量	✅	✅	✅	✅
標準計量	✅	✅	✅	✅
固定取樣率	✅	✅	✅	✅
離線儲存和自動重試	✅	✅	✅	✅
例外狀況報告	✅	✅	✅	✅
記錄集合	✅	⚠️	✅	✅
自訂事件	⚠️	⚠️	⚠️	✅
Microsoft Entra 驗證	✅	✅	✅	✅
即時計量	✅	✅	✅	✅
即時計量篩選	✅	❌	❌	❌
偵測 VM/VMSS 和 App Service 的資源內容	✅	❌	✅	✅
偵測 Azure Kubernetes Service (AKS) 的資源內容和 Functions	❌	❌	❌	✅
使用追蹤可用性 API 產生的可用性測試事件	❌	❌	❌	✅
依匿名使用者識別碼和綜合來源篩選要求、相依性、記錄和例外狀況	❌	❌	❌	✅
依作業名稱篩選相依性、記錄和例外狀況	❌	❌	❌	✅
調適型取樣	❌	❌	❌	✅
分析工具	❌	❌	❌	⚠️
快照偵錯工具	❌	❌	❌	❌

索引鍵

• ✅ 這項功能適用於全部擁有正式支援的客戶。
• ⚠ 這項功能目前提供於公開預覽。 請參閱 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 監視器。

在 Grafana 中，為什麼我會看到 Status: 500. Can't visualize trace events using the trace visualizer？

您可以嘗試將原始文字記錄而非 OpenTelemetry 追蹤視覺化。

在 Application Insights 中，'Traces' 資料表會儲存原始文字記錄以供診斷之用。 其有助於識別及相互關聯與使用者要求、其他事件和例外狀況報告相關的追蹤。 不過，'Traces' 資料表不會直接參與 Grafana 等視覺效果工具中的端對端交易檢視 (瀑布圖)。

隨著雲端原生做法日益普及，遙測集合和術語也逐漸演進。 OpenTelemetry 成為收集和檢測遙測資料的標準。 在此背景下，'Traces'一詞有了全新定義。 OpenTelemetry 中的 'Traces' 指的不是原始記錄，而是更豐富的結構化遙測形式，其中包含代表個別工作單位的範圍。 這些範圍對於建構詳細的交易檢視至關重要，能提供更佳的雲端原生應用程式監視和診斷。

疑難排解

ASP.NET Core

步驟 1：啟用診斷記錄

Azure 監視器匯出工具使用 EventSource 進行其內部記錄。 匯出工具記錄可供任何 EventListener 使用，方法是加入宣告名為 OpenTelemetry-AzureMonitor-Exporter的來源。 如需疑難排解步驟，請參閱 GitHub 上的 OpenTelemetry 疑難排解。

步驟 2：測試應用程式主機與擷取服務之間的連線

Application Insights 軟體開發工具包 （SDK） 和代理程式會傳送遙測，以在擷取端點取得 REST 呼叫。 若要測試從 Web 伺服器或應用程式主機電腦到擷取服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

已知問題

下列項目是 Azure 監視器 OpenTelemetry 匯出工具的已知問題：

• 相依性遙測資料中缺少操作名稱。 缺少操作名稱會導致失敗，並對性能索引標籤體驗產生負面影響。

• 要求和相依性遙測資料中缺少裝置型號。 缺少裝置型號會對裝置世代分析產生不利影響。

.NET

步驟 1：啟用診斷記錄

Azure 監視器匯出工具使用 EventSource 進行其內部記錄。 匯出工具記錄可供任何 EventListener 使用，方法是加入宣告名為 OpenTelemetry-AzureMonitor-Exporter的來源。 如需疑難排解步驟，請參閱 GitHub 上的 OpenTelemetry 疑難排解。

步驟 2：測試應用程式主機與擷取服務之間的連線

Application Insights SDK 和代理程式會傳送遙測，以擷取為 REST 呼叫擷取到我們擷取的端點。 若要測試從 Web 伺服器或應用程式主機電腦到擷取服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

已知問題

下列項目是 Azure 監視器 OpenTelemetry 匯出工具的已知問題：

• 相依性遙測資料中缺少操作名稱。 缺少操作名稱會導致失敗，並對性能索引標籤體驗產生負面影響。

• 要求和相依性遙測資料中缺少裝置型號。 缺少裝置型號會對裝置世代分析產生不利影響。

Java

步驟 1：啟用診斷記錄

根據預設，Azure Monitor Application Insights 中啟用診斷記錄。 如需詳細資訊，請參閱疑難排解指南：適用於 JAVA 的 Azure 監視器 Application Insights。

步驟 2：測試應用程式主機與擷取服務之間的連線

Application Insights SDK 和代理程式會傳送遙測，以擷取為 REST 呼叫擷取到我們擷取的端點。 若要測試從 Web 伺服器或應用程式主機電腦到擷取服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

已知問題

• 如果從瀏覽器下載 Application Insights 用戶端程式庫進行安裝，有時下載的 JAR 檔案已損毀，大小約為來源檔案的一半。 如果遇到此問題，請通過運行 curl 或 wget 命令下載 JAR 檔案，如下列範例顯示叫用命令：

  curl --location --output applicationinsights-agent-3.6.2.jar https://github.com/microsoft/ApplicationInsights-Java/releases/download//applicationinsights-agent-3.6.2.jar
  

  wget --output-document=applicationinsights-agent-3.6.2.jar https://github.com/microsoft/ApplicationInsights-Java/releases/download//applicationinsights-agent-3.6.2.jar
  

  注意

  範例命令叫用適用於 Application Insights for Java 版本 3.4.11。 若要查找當前版本的 Application Insights for Java 的版本號和 URL 位址，請參閱 https://github.com/microsoft/ApplicationInsights-Java/releases。

JAVA 原生

下列步驟適用於 Spring Boot 原生應用程式。

步驟 1：驗證 OpenTelemetry 版本

應用程式啟動過程中，您可能會注意到以下訊息：

WARN  c.a.m.a.s.OpenTelemetryVersionCheckRunner - The OpenTelemetry version is not compatible with the spring-cloud-azure-starter-monitor dependency.
The OpenTelemetry version should be <version>

在這種情況下，您必須按照 Spring Boot starter 中的 OpenTelemetry 文件導入 OpenTelemetry 物料清單。

步驟 2：啟用自我診斷

如果未按預期工作，則可以在 DEBUG 等級啟用自我診斷以取得深入解析。 若要這樣做，請使用 APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL 環境變數，將自我診斷等級設定為 ERROR、WARN、INFO、DEBUG 或 TRACE。

若要在運行 Docker 容器時在 DEBUG 等級啟用自診斷，請執行下列命令：

docker run -e APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL=DEBUG <image-name>

注意

對應使用 Docker 映像名稱取代 <image-name>。

協力廠商資訊免責聲明

Microsoft不會就這些獨立第三方產品的效能或可靠性進行默示或其他擔保。

Node.js

步驟 1：啟用診斷記錄

Azure 監視器匯出工具使用 OpenTelemetry API 記錄器進行內部記錄。 若要啟用記錄器，請執行下列程式碼片段：

const { diag, DiagConsoleLogger, DiagLogLevel } = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");

const provider = new NodeTracerProvider();
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
provider.register();

步驟 2：測試應用程式主機與擷取服務之間的連線

Application Insights SDK 和代理程式會傳送遙測，以擷取為 REST 呼叫擷取到我們擷取的端點。 若要測試從 Web 伺服器或應用程式主機電腦到擷取服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

已知問題

下列項目是 Azure 監視器 OpenTelemetry 匯出工具的已知問題：

• 相依性遙測資料中缺少操作名稱。 缺少操作名稱會導致失敗，並對性能索引標籤體驗產生負面影響。

• 要求和相依性遙測資料中缺少裝置型號。 缺少裝置型號會對裝置世代分析產生不利影響。

• 相依性名稱缺少資料庫伺服器名稱。 由於不包括資料庫伺服器名稱，因此 OpenTelemetry 匯出程式會錯誤地將具有相同名稱的資料表彙總到不同的伺服器上。

Python

啟用診斷記錄

Microsoft Azure 監視器匯出工具使用 Python 標準記錄程式庫進行其內部記錄。 對於異常活動，OpenTelemetry API 和 Azure 監視器匯出工具記錄會以 WARNING 或 ERROR 嚴重性層級來加以記錄。 INFO 嚴重性層級用來表示一般或成功的活動。

根據預設，Python 記錄程式庫將嚴重性等級設定為 WARNING。 因此，您必須變更嚴重性等級，才能在此嚴重性設定下查看記錄。 下列範例示範程式碼如何將所有嚴重性層級的記錄輸出到主控台和檔案：

...
import logging

logging.basicConfig(format = "%(asctime)s:%(levelname)s:%(message)s", level = logging.DEBUG)

logger = logging.getLogger(__name__)
file = logging.FileHandler("example.log")
stream = logging.StreamHandler()
logger.addHandler(file)
logger.addHandler(stream)
...

測試應用程式主機與擷取服務之間的連線

Application Insights SDK 和代理程式會傳送遙測，以擷取為 REST 呼叫擷取到我們擷取的端點。 若要測試從 Web 伺服器或應用程式主機電腦到擷取服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

避免重複遙測

如果您建立多個處理器或匯出工具的執行個體，通常會造成重複遙測。 請確定您一次只針對遙測要素執行一個匯出工具和處理器 (記錄、計量和分散式追蹤)。

下列各節說明可能導致重複遙測的案例。

Azure Functions 中的重複追蹤記錄

如果您在 Application Insights 內看到每個追蹤記錄的一對項目，您可能已啟用下列類型的記錄檢測：

• Azure Functions 中的原生記錄檢測
• 散發內的 azure-monitor-opentelemetry 記錄檢測

若要避免重複，您可以停用散發的記錄，但讓 Azure Functions 中的原生記錄檢測保持啟用。 若要達成此目標，請將 OTEL_LOGS_EXPORTER 環境變數設定為 None。

Azure Functions 中「一律開啟」的重複遙測

如果 Azure Functions 中的 [一律開啟] 設定設為開啟，Azure Functions 會在每次執行完成後，讓某些程序在背景中執行。 例如，假設您有一個每五分鐘呼叫 configure_azure_monitor 的函數。 20 分鐘之後，您可能會有四個計量匯出工具同時執行。 這種情況可能是重複計量遙測的來源。

在此情況下，請將 [一律開啟] 設定為 [關閉]，或嘗試手動關閉每個 configure_azure_monitor 呼叫之間的提供者。 若要關閉每個提供者，請針對每個目前的計量、追蹤器和記錄器提供者執行關機呼叫，如下列程式碼所示：

get_meter_provider().shutdown()
get_tracer_provider().shutdown()
get_logger_provider().shutdown()

Azure Workbooks 和 Jupyter Notebooks

Azure Workbooks 和 Jupyter Notebook 可能會讓匯出工具在背景中執行。 若要防止重複遙測，請先清除快取，再呼叫 configure_azure_monitor。

遺失來自 FastAPI 或 Flask 應用程式的要求遙測

如果您遺漏要求數據表數據，但未包含其他類別，則 HTTP 架構可能未經過檢測。 如果您未正確建import構宣告，則可以使用適用於 Python 的 Azure 監視器 OpenTelemetry Distro 用戶端連結庫，在 FastAPI 和 Flask 應用程式中發生這種情況。 您可能在呼叫 函configure_azure_monitor式以偵測 FastAPI 和 Flask 連結庫之前，分別匯入 fastapi.FastAPI 或 flask.Flask 。 例如，下列程式代碼無法成功檢測 FastAPI 和 Flask 應用程式：

# FastAPI

from azure.monitor.opentelemetry import configure_azure_monitor
from fastapi import FastAPI

configure_azure_monitor()

app = FastAPI()

# Flask

from azure.monitor.opentelemetry import configure_azure_monitor
from flask import Flask

configure_azure_monitor()

app = Flask(__name__)

相反地，我們建議您匯 fastapi 入 或 flask 模組，然後呼叫 來設定 configure_azure_monitor OpenTelemetry 以在存取 fastapi.FastAPI 或 flask.Flask之前使用 Azure 監視器：

# FastAPI

from azure.monitor.opentelemetry import configure_azure_monitor
import fastapi

configure_azure_monitor()

app = fastapi.FastAPI(__name__)

# Flask

from azure.monitor.opentelemetry import configure_azure_monitor
import flask

configure_azure_monitor()

app = flask.Flask(__name__)

或者，您可以在匯入 fastapi.FastAPI 或 flask.Flask之前呼叫 configure_azure_monitor ：

# FastAPI

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

from fastapi import FastAPI

app = FastAPI(__name__)

# Flask

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

from flask import Flask

app = Flask(__name__)

支援

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

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 問題頁面。

JAVA 原生

• 針對 Azure 支援問題，請開啟 Azure 支援票證。
• 針對 OpenTelemetry 問題，請直接連絡 OpenTelemetry 社群。
• 有關 Spring Boot 原生應用程式的未解決問題清單，請參閱 GitHub 問題頁面。
• 有關 Quarkus 原生應用程式的未解決問題清單，請參閱 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 意見反應論壇中提出功能要求。