共用方式為

設定 Azure 監視器 OpenTelemetry

本指南說明如何使用 Azure 監視器 OpenTelemetry 散發版本在 Azure 監視器 Application Insights 中設定 OpenTelemetry (OTel)。 適當的設定可確保跨 .NET、Java、Node.js和 Python 應用程式進行一致的遙測數據收集，以便進行更可靠的監視和診斷。

附註

針對 Azure 函數應用，請參閱 在 Azure 函數中使用 OpenTelemetry。

連接字串

Application Insights 中的連接字串會定義傳送遙測資料的目標位置。

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

  • 把它加 UseAzureMonitor() 到你的 program.cs 檔案裡。

        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>";
    });

    var app = builder.Build();

    app.Run();

  • 設定環境變數。

    APPLICATIONINSIGHTS_CONNECTION_STRING=<YOUR-CONNECTION-STRING>

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

      {
    "AzureMonitor": {
        "ConnectionString": "<YOUR-CONNECTION-STRING>"
    }
  }

附註

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

  1. Code
  2. 環境變數
  3. 組態檔

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

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

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

// 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 ResourceBuilder to add the custom resource attributes to all signals.
    // Custom resource attributes should be added AFTER AzureMonitor to override the default ResourceDetectors.
    .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 Monitor 的 OpenTelemetry 發行版支援兩種追蹤取樣策略，並且（可選地）讓你將應用程式日誌與追蹤取樣決策對齊。 取樣器會將選定的取樣比率或速率附加到匯出的區段，讓 Application Insights 能準確調整經驗數。 欲了解概念性概述，請參閱 了解更多關於抽樣的資訊。

重要

  • 取樣決策適用於追蹤 (範圍)。
  • 指標從不抽樣。
  • 日誌 預設不會被取樣。 你可以選擇對 日誌採用基於痕跡的取樣 ，這樣屬於未取樣痕跡的日誌就會被刪除。 欲了解更多細節， 請設定日誌的追蹤取樣。

附註

如果您在 Application Insights 中看到意外收費或高成本，常見原因包括遙測量過高、資料擷取激增，以及取樣設定錯誤。 要開始排除故障，請參閱 Application Insights 中的「排除高資料擷取問題」。

使用環境變數配置抽樣

使用標準的 OpenTelemetry 環境變數選擇取樣器並提供其參數：

  • OTEL_TRACES_SAMPLER — 取樣器類型

    • microsoft.fixed.percentage ——取樣一小部分痕跡。
    • microsoft.rate_limited — 限制每秒追蹤數上限。

  • OTEL_TRACES_SAMPLER_ARG — 取樣器參數

    • 對於 microsoft.fixed.percentage：值為 0.0–1.0 （例如 0.1 = ~10%）。
    • 對於 microsoft.rate_limited： 每秒最大痕跡數 （例如， 1.5）。

以下範例展示了如何利用環境變數配置取樣。

固定百分比抽樣（~10%）

export OTEL_TRACES_SAMPLER="microsoft.fixed.percentage"
export OTEL_TRACES_SAMPLER_ARG=0.1

速率限制取樣（~1.5 trace/sec）

export OTEL_TRACES_SAMPLER="microsoft.rate_limited"
export OTEL_TRACES_SAMPLER_ARG=1.5

在程式碼中配置取樣

附註

當同時設定程式碼層級的選項與環境變數時， 環境變數會優先。 預設取樣器的行為會因語言而異，請參見以下分頁。

固定百分比抽樣

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.SamplingRatio = 0.1F; // ~10%
});
var app = builder.Build();
app.Run();

速率限制取樣

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.TracesPerSecond = 1.5; // ~1.5 traces/sec
});
var app = builder.Build();
app.Run();

附註

如果你沒有在程式碼或環境變數中設定取樣器，Azure Monitor 預設會使用 ApplicationInsightsSampler 。

秘訣

使用固定百分比抽樣且不確定取樣率設定時，建議從 5%0.05（ ）。 根據故障與效能面板中顯示的操作準確度調整速率。 任何抽樣都會降低準確度，因此我們建議在 OpenTelemetry 指標上發出警示，因為這些指標不會受到抽樣影響。

為日誌配置基於追蹤的取樣

啟用後，屬於 未取樣痕跡 的日誌紀錄會被刪除，以確保日誌與痕跡取樣保持一致。

  • 當日誌記錄具有有效的 SpanId時，該記錄被視為追蹤的一部分。
  • 若關聯的追蹤 TraceFlags 顯示 未取樣，日誌紀錄將 被丟棄。
  • 沒有任何痕跡上下文的日誌記錄不會受影響。
  • 此功能 預設是關閉的。 賦能即語言，請參見以下標籤。

在您的設定中請使用以下設定來啟用基於痕跡的日誌取樣：

builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.EnableTraceBasedLogsSampler = true;
});

即時計量

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

重要

如需適用於 Beta、預覽版或尚未發行至正式運作的 Azure 功能的法律條款，請參閱 Microsoft 適用於 azure 預覽版的補充使用規定 。

此功能預設為啟用。

設定 Distro 時，使用者可以停用即時計量。

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

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

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

如需詳細資訊，請參閱我們針對每個支援的語言連結的專用Microsoft Entra 驗證頁面。

如需設定 Entra ID 驗證的相關信息，請參閱 application Insights 的 Microsoft Entra 驗證

離線儲存和自動重試

當應用程式與 Application Insights 中斷連線時，Azure Monitor 基於 OpenTelemetry 的解決方案會暫存遙測資料，並在最多 48 小時內重試傳送。 如需數據處理建議，請參閱 匯出和刪除私人數據。 高負載應用程式偶爾會因為以下兩個原因而捨棄遙測資料：超過允許的時間或超過最大檔案大小。 必要時，產品會將最近的事件優先於舊事件。

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

  • 窗戶

    • %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 can't 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 資源屬性的值。 如果在 service.name 中也提供 OTEL_RESOURCE_ATTRIBUTES，則會優先使用 OTEL_SERVICE_NAME。

修訂 URL 查詢字串

若要修訂 URL 查詢字串，請關閉查詢字串集合。 如果您使用 SAS 令牌呼叫 Azure 記憶體，建議您使用此設定。

當您使用 Azure.Monitor.OpenTelemetry.AspNetCore 散發套件時，會同時包含 ASP.NET Core 和 HttpClient 檢測程式庫。 我們的散發套件預設會將查詢字串修訂設定為關閉。

若要變更此行為，您必須將環境變數設定為 true 或 false。

  • ASP.NET 核心檢測：預設會停用 OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION 查詢字串修訂。 若要啟用，請將此環境變數設定為 false。

  • Http 用戶端檢測：預設會停用 OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION 查詢字串修訂。 若要啟用，請將此環境變數設定為 false。

計量匯出間隔

您可以使用環境變數來設定計量匯出間隔 OTEL_METRIC_EXPORT_INTERVAL 。

OTEL_METRIC_EXPORT_INTERVAL=60000

預設值為 60000 毫秒（60 秒）。 此設定可控制 OpenTelemetry SDK 匯出計量的頻率。

秘訣

Azure 監視器計量和 Azure 監視器工作區會以固定的 60 秒間隔內嵌自定義計量。 被更頻繁傳送的計量會每隔 60 秒緩衝並處理一次。 Log Analytics 會以傳送的間隔記錄計量，這可能會以較短的間隔增加成本，並以較長的間隔延遲可見度。

如需參考，請參閱下列 OpenTelemetry 規格：

  • Last updated on