共用方式為

設定 Azure 監視器 OpenTelemetry

  • 發行項

本文涵蓋 Azure 監視器 OpenTelemetry 發行版本的組態設定。

Connection string

Application Insights 中的連接字串會定義傳送遙測資料的目標位置，確保其到達適當的資源以進行監視和分析。

使用下列三種方式之一來設定連接字串：

  • 在類別中program.cs，將 新增UseAzureMonitor()至應用程式啟動。

    // Create a new ASP.NET Core web application builder.    
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
    options.ConnectionString = "<Your Connection String>";
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.    
app.Run();

  • 設定環境變數。

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

  • 將下列區段新增至組 appsettings.json 態檔。

    {
  "AzureMonitor": {
      "ConnectionString": "<Your Connection String>"
  }
}

注意

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

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

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

針對支援的語言，Azure 監視器 OpenTelemetry Distro 會自動偵測資源內容，並提供您元件的雲端角色名稱和雲端角色實例屬性的預設值。 不過，您可能想要將預設值覆寫為對您的小組有意義的專案。 雲端角色名稱值會顯示在應用程式對應上，做為節點底下的名稱。

透過資源屬性來設定雲端角色名稱和雲端角色執行個體。 雲端角色名稱會使用 service.namespace 和 service.name 屬性，但如果 service.namespace 未設定，則會回復為 service.name。 雲端角色執行個體會使用 service.instance.id 屬性值。 如需資源標準屬性的資訊，請參閱 OpenTelemetry 語意慣例。

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Configure the OpenTelemetry tracer provider to add the resource attributes to all traces.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
    builder.ConfigureResource(resourceBuilder => 
        resourceBuilder.AddAttributes(resourceAttributes)));

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

啟用取樣

您可能想要啟用取樣來減少您的資料擷取量，以降低成本。 Azure 監視器可提供一個以「取樣率」來填入事件自訂固定比率取樣器，Application Insights 會將其轉換為 ItemCount。 固定比率取樣器可確保精確的體驗和事件計數。 取樣器的設計目的是要跨服務保留您的追蹤，並與舊版 Application Insights 軟體開發工具包 （SDK） 互通。 如需詳細資訊，請參閱深入了解取樣。

注意

計量和記錄不會受到取樣影響。

取樣器會預期一個介於 0 到 1 (含) 之間的取樣率。 0.1 的比率表示大約會傳送 10% 的追蹤資料。

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    o.SamplingRatio = 0.1F;
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

提示

使用固定速率/百分比取樣而且您不確定在何處設定取樣率，請從 5% 開始 (也就是 0.05 的取樣率)，並根據失敗和效能刀鋒窗格中所示作業的精確度來調整比率。 較高的比率通常會導致較高的精確度。 不過，「任何的」取樣都會影響精確度，因此我們建議在 OpenTelemetry 計量上發出警示，這不會受到取樣的影響。

即時計量

即時計量 提供即時分析儀錶板，以深入瞭解應用程式活動和效能。

重要

請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。

此功能預設為啟用。

設定散發版本時，使用者可以停用即時計量。

builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
	// Disable the Live Metrics feature.
    options.EnableLiveMetrics = false;
});

啟用 Microsoft Entra ID (先前稱為 Azure AD) 驗證

您可能想要啟用 Microsoft Entra 驗證，以建立更安全的 Azure 連線，防止未經授權的遙測擷取到您的訂用帳戶。

我們支援 Azure 身分識別所提供的認證類別。

  • 我們建議針對本機開發使用 DefaultAzureCredential。
  • 建議針對系統指派和使用者指派的受控識別使用 ManagedIdentityCredential。
    • 若為系統指派，請使用不含參數的預設建構函式。
    • 針對使用者指派，請將用戶端識別碼提供給建構函式。
  • 我們建議針對服務主體使用 ClientSecretCredential。
    • 為建構函式提供租用戶識別碼、用戶端識別碼和用戶端密碼。

  1. 安裝最新的 Azure.Identity 套件：

    dotnet add package Azure.Identity

  2. 提供所需的認證類別：

    // Create a new ASP.NET Core web application builder.    
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
    // Set the Azure Monitor credential to the DefaultAzureCredential.
    // This credential will use the Azure identity of the current user or
    // the service principal that the application is running as to authenticate
    // to Azure Monitor.
    options.Credential = new DefaultAzureCredential();
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

離線儲存和自動重試

為了改善可靠性和復原能力，當應用程式失去與 Application Insights 的連線時，Azure 監視器 OpenTelemetry 型供應項目依預設會寫入離線/本機儲存空間。 它會將應用程式遙測儲存至磁碟，並定期嘗試再次傳送最多 48 小時。 在高負載應用程式中，遙測偶爾會因為兩個原因而卸除。 首先是超過允許的時間，其次是超過檔案大小上限，或 SDK 沒有機會清除檔案時。 如果我們需要選擇，則該產品會儲存比舊事件更多的最新事件。 深入瞭解

發行版本套件包含 AzureMonitorExporter，預設會針對離線儲存使用下列其中一個位置 (依優先順序列出)：

  • Windows
    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor
  • 非 Windows
    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

若要覆寫預設的目錄，您應該設定 AzureMonitorOptions.StorageDirectory。

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that cannot be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

若要停用此功能，您應該設定 AzureMonitorOptions.DisableOfflineStorage = true。

啟用 OTLP 匯出工具

您可以讓 OpenTelemetry 通訊協定 (OTLP) 匯出工具與 Azure 監視器匯出工具一起將遙測傳送至兩個位置。

注意

OTLP 匯出工具的顯示只是為了方便起見。 我們並未正式支援 OTLP 匯出工具，或其下游的任何元件或協力廠商體驗。

  1. 在您的專案中安裝 OpenTelemetry.Exporter.OpenTelemetryProtocol 套件。

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. 新增下列程式碼片段。 此範例假設您的 OpenTelemetry 收集器正在執行 OTLP 接收器。 如需詳細資訊，請參閱 GitHub 範例。

    // Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Add the OpenTelemetry OTLP exporter to the application.
// This exporter will send telemetry data to an OTLP receiver, such as Prometheus
builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

OpenTelemetry 設定

使用 Azure 監視器 OpenTelemetry 發行版本時，可以透過環境變數存取下列 OpenTelemetry 設定。

環境變數 描述
APPLICATIONINSIGHTS_CONNECTION_STRING 針對您的 Application Insights 資源將其設定為連接字串。
APPLICATIONINSIGHTS_STATSBEAT_DISABLED 將它設定為 true ，以退出退出內部計量集合。
OTEL_RESOURCE_ATTRIBUTES 要用作資源屬性的索引鍵/值組。 如需資源屬性的詳細資訊，請參閱資源 SDK 規格。
OTEL_SERVICE_NAME 設定 service.name 資源屬性的值。 如果在 OTEL_RESOURCE_ATTRIBUTES 中也提供 service.name，則會優先使用 OTEL_SERVICE_NAME。

常見問題集

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

什麼是 OpenTelemetry？

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

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

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

OpenTelemetry 的主要價值主張在於，其為廠商中性並提供跨語言的一致 API/SDK。

一段時間後，我們相信 OpenTelemetry 能讓 Azure 監視器客戶觀察使用我們支援語言以外的語言所撰寫的應用程式。 這也會擴充您可以透過一組多樣化的檢測程式庫所收集的資料類型。 此外，OpenTelemetry 軟體開發工具包（SDK）的規模比其前身 Application Insights SDK 更能發揮效能。

最後，OpenTelemetry 也會配合 Microsoft 的策略採用開放原始碼。

OpenTelemetry 的狀態為何？

請參閱 OpenTelemetry 狀態。

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

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

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

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

秉持 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 發行版本？

請查看 .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 監視器 OpenTelemetry Distro。 這是開始使用的一行程式碼。

針對所有其他 .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） 和函式 ❌ ❌ ❌ ✅
可用性測試範圍篩選 ❌ ❌ ❌ ✅
自動填入使用者識別碼、已驗證的使用者識別碼和使用者 IP ❌ ❌ ❌ ✅
手動覆寫/設定作業名稱、使用者識別碼或已驗證的使用者識別碼 ❌ ❌ ❌ ✅
調適型取樣 ❌ ❌ ❌ ✅
分析工具 ❌ ❌ ❌ ⚠️
快照偵錯工具 ❌ ❌ ❌ ❌

索引鍵

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 的疑難排解頁面。

支援

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

OpenTelemetry 意見反應

若要提供意見反應：