共用方式為

設定 Azure 監視器 OpenTelemetry

  • 發行項

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

Connection string

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. 代碼
  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 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(_testResourceAttributes));

// 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(options =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    options.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)、預覽版，或尚未正式發行的版本) 的法律條款。

此功能預設為啟用。

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

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。

修訂 URL 查詢字串

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

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

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

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