共用方式為

新增和修改適用於 .NET、Java、Node.js 和 Python 應用程式的 Azure 監視器 OpenTelemetry

本指南提供在 Azure Monitor Application Insights 中整合和自定義 OpenTelemetry（OTel）工具的說明。

若要深入瞭解 OpenTelemetry 概念，請參閱 OpenTelemetry 概觀 或 OpenTelemetry 常見問題。

附註

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

自動收集資料

發行版本會藉由統合 OpenTelemetry 檢測程式庫來自動收集資料。

包含的工具程式庫

請求

依賴

Logging

  • ILogger

若要減少或增加傳送至 Azure 監視器的記錄數目，請設定記錄以設定適當的記錄層級或套用篩選。 例如，您可以選擇只傳送 Warning 和 Error 記錄至 OpenTelemetry/Azure 監視器。 OpenTelemetry 不會控制記錄路由或篩選 -您的 ILogger 設定會做出這些決策。 如需了解如何設定 ILogger 的詳細資訊，請參閱 設定日誌。

如需有關ILogger的詳細資訊，請參閱C# 和 .NET 中的記錄以及程式代碼範例。

腳注

  • ¹：支援自動報告未處理/未攔截的例外狀況
  • ²：支援 OpenTelemetry 計量

附註

Azure 監視器 OpenTelemetry 發行版本包含自訂對應和邏輯，可自動發出 Application Insights 標準計量。

秘訣

全部 OpenTelemetry 計量，無論是從檢測程式庫自動收集，還是從自訂程式碼中手動收集，目前都會被視為 Application Insights 的「自訂計量」，以供計費之用。 深入瞭解。

新增社群檢測程式庫

您可以從 OpenTelemetry 社群中納入追蹤程式庫，自動收集更多資料。

警告

我們不支援或保證社群檢測程式庫的品質。 如果要為我們的發行版提出建議，可以在我們的 意見反應社群中發表相關貼文或進行按讚。 請注意，有些是以實驗性 OpenTelemetry 規格為基礎，而且可能會帶來未來的重大變更。

若要新增社群程式庫，請在新增程式庫的 NuGet 套件之後，使用 ConfigureOpenTelemetryMeterProvider 或 ConfigureOpenTelemetryTracerProvider 方法。

下列範例示範如何新增 運行時間檢測 來收集額外的計量：

dotnet add package OpenTelemetry.Instrumentation.Runtime 

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

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddRuntimeInstrumentation());

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

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

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

資源偵測器

資源偵測器會在啟動時探索環境中繼資料，並填入 OpenTelemetry 資源屬性 ，例如 service.name、 cloud.provider和 cloud.resource_id。 此中繼資料可支援 Application Insights 中的體驗，例如 Application Map 和計算連結，並改善追蹤、計量和記錄之間的相互關聯。

秘訣

資源屬性描述程序及其環境。 跨度屬性描述單一作業。 將資源屬性用於應用程式層級屬性，例如 service.name。

支援的環境

環境 偵測的運作方式 註釋
Azure App Service 語言 SDK 或 Azure 監視器發行版本會讀取已知的 App Service 環境變數和主機中繼資料 當您使用本文中的指引時，可與 .NET、Java、Node.js和 Python 搭配使用。
Azure Functions 請參閱 Azure Functions OpenTelemetry 操作說明 所有 Azure Functions 的指導性內容都集中在那裡。
Azure 虛擬機器 語言 SDK 或發行套件會查詢 Azure 實例中繼資料服務 請確定 VM 可以存取執行個體中繼資料服務端點。
Azure Kubernetes Service （AKS） 使用 OpenTelemetry 收集器 k8sattributes 處理器來新增 Kubernetes 中繼資料 建議用於所有執行於 AKS 的語言。
Azure 容器應用程式 偵測器會在可用時對環境變數和資源識別碼進行映射。 您也可以設定 OTEL_RESOURCE_ATTRIBUTES 以填補間隙。

手動和自動儀器

  • 自動化儀器和 Azure 監視器發佈版可在支援的 Azure 環境中執行時啟用資源檢測。

  • 對於手動設定，您可以使用標準 OpenTelemetry 選項直接設定資源屬性：

    # Applies to .NET (ASP.NET/ASP.NET Core), Java, Node.js, and Python
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

    在 Windows PowerShell 上：

    $Env:OTEL_SERVICE_NAME="my-service"
$Env:OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

OTLP 擷取考量

  • Application Insights 用 service.name 來衍生雲端角色名稱。 為每個服務選擇一個穩定的名稱，以避免應用程式對應中的節點碎片化。
  • cloud.resource_id 改善與 Azure 資源的計算連結。 如果遺漏此屬性，某些體驗可能不會顯示產生資料的 Azure 資源。

收集自訂遙測資料

本節說明如何從您的應用程式中收集自訂遙測。

視您的語言和訊號類型而定，有不同的方式可以收集自訂遙測，其中包括：

  • OpenTelemetry 應用程式介面
  • 語言特定的記錄/計量程式庫
  • Application Insights 經典 API

附註

不支援 Java 的 微分尺追蹤 API 。

下表代表目前支援的自訂遙測類型：

語言 自訂事件 自訂計量 相依性 例外狀況 頁面檢視 請求事項 痕跡
ASP.NET 核心
   OpenTelemetry 應用程式介面 是的 是的 是的 是的
    ILogger 應用程式介面 是的
   AI 傳統 API
爪哇島
   OpenTelemetry 應用程式介面 是的 是的 是的 是的
   Logback、Log4j、JUL 是的 是的
   微計計量 是的
   AI 傳統 API 是的 是的 是的 是的 是的 是的 是的
Node.js
   OpenTelemetry 應用程式介面 是的 是的 是的 是的
Python（編程語言）
   OpenTelemetry 應用程式介面 是的 是的 是的 是的
   Python 記錄模組 是的
   事件延伸模組 是的 是的

附註

Application Insights Java 3.x 和 Application Insights Node.js 3.x 會從 Application Insights 傳統 API 收集遙測。 此行為可簡化升級，並暫時支援自定義遙測，直到 OpenTelemetry API 包含所有自定義遙測類型為止。

新增自訂計量

在此內容中，自訂計量字詞是指手動檢測您的程式碼，以收集 OpenTelemetry 檢測程式庫自動收集以外的額外計量。 若要深入了解如何使用計量，請參閱 Application Insights 中的計量。

OpenTelemetry API 提供六個度量「工具」來涵蓋各種的度量案例，並在「度量瀏覽器」中視覺化度量時，您需要選擇正確的「彙總類型」。 使用 OpenTelemetry 計量 API 來傳送計量，以及使用檢測程式庫時，這項需求是必要的。

下表顯示每個 OpenTelemetry Metric Instruments 的建議 匯總類型 。

OpenTelemetry 檢測 Azure 監視器彙總類型
計數器 合計
非同步計數器 合計
長條圖 最小值、最大值、平均值、總和和計數
非同步量測計 平均
UpDownCounter 合計
非同步 UpDownCounter 合計

警告

在大部分情況下，其他匯總類型並不有意義。

OpenTelemetry 規格會描述儀器，並提供何時可以使用每個儀器的範例。

秘訣

直方圖是最多用途且最接近於 Application Insights GetMetric 傳統 API。 Azure 監視器目前會將長條圖檢測扁平化為五種支援的彙總類型，且對百分位數的支援正在進行中。 雖然較不多才多藝，但其他 OpenTelemetry 儀器對應用程式的效能影響較小。

長條圖範例

應用程式啟動必須依名稱訂閱計量：

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

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

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

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

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

Meter 必須使用相同的名稱初始化：

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

反例

應用程式啟動必須依名稱訂閱計量：

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

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

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

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

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

Meter 必須使用相同的名稱初始化：

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

量測計範例

應用程式啟動必須依名稱訂閱計量：

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

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

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

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

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

Meter 必須使用相同的名稱初始化：

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));

private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID, and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
    }
}

新增自訂例外狀況

選取檢測程式庫會自動報告 Application Insights 的例外狀況。 不過，您可能想要手動報告超出檢測程式庫報告範圍的例外狀況。 例如，您的程式碼攔截到的例外狀況通常不會報告。 您可能想要對其進行報告，以便在相關的體驗中吸引注意，包括失敗區段和端對端交易檢視。

  • 若要使用活動記錄例外狀況：

    // Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • 若要使用 ILogger 記錄例外狀況：

    // Create a logger using the logger factory. The logger category name is used to filter and route log messages.
var logger = loggerFactory.CreateLogger(logCategoryName);

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

新增自訂範圍

您可能會想要在兩個案例中新增自訂範圍。 首先，檢測程式庫尚未收集相依性要求時。 其次，當您希望將應用程式流程模型化為端對端交易視圖中的一個環節時。

附註

Activity 命名空間中的 ActivitySource 和 System.Diagnostics 類別分別代表 OpenTelemetry 的 Span 和 Tracer 概念。 您可以使用其建構函式直接建立 ActivitySource，而不是使用 TracerProvider。 必須使用 ActivitySource 明確將每個 TracerProvider 類別連接到 AddSource()。 這是因為 OpenTelemetry 追蹤 API 的部分會直接併入 .NET 執行環境。 若要深入瞭解，請參閱 OpenTelemetry .NET 追蹤 API 簡介。

// Define an activity source named "ActivitySourceName". This activity source will be used to create activities for all requests to the application.
internal static readonly ActivitySource activitySource = new("ActivitySourceName");

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

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName". This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));

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

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

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

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

StartActivity 預設為 ActivityKind.Internal，但您可以提供其他任何 ActivityKind。 ActivityKind.Client、ActivityKind.Producer 和 ActivityKind.Internal 會對應於 Application Insights dependencies。 ActivityKind.Server 和 ActivityKind.Consumer 會對應於 Application Insights requests。

傳送自訂事件

Application Insights 會將自定義事件儲存在數據表中 customEvents 。 分析、篩選和可視化的其中一種方法是使用Application Insights使用體驗。

如果您想要將用戶端互動事件的集合自動化，您可以在 JavaScript SDK 中使用外掛程式。

自定義事件處於公開預覽狀態，並使用 Azure.Monitor.OpenTelemetry.AspNetCore 1.3.0-beta.3。

重要

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

若要使用 CustomEvent傳送 ILogger ，請在訊息範本中設定 "microsoft.custom_event.name" 屬性。

// Create a logger factory and configure OpenTelemetry with Azure Monitor
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddOpenTelemetry(options =>
        {
            options.AddAzureMonitorLogExporter();
        });
});

// Create a logger for the specified category
var logger = loggerFactory.CreateLogger(logCategoryName);

// Log a custom event with a custom name and additional attribute
// The 'microsoft.custom_event.name' value will be used as the name of the customEvent
logger.LogInformation("{microsoft.custom_event.name} {additional_attrs}", "test-event-name", "val1");

修改遙測

本節說明如何修改遙測。

新增範圍屬性

這些屬性可能包括將自訂屬性新增至遙測數據。 您也可以使用屬性來設定 Application Insights 結構描述中的選用欄位，例如用戶端 IP。

將自訂屬性新增至範圍

您新增至範圍的任何 屬性 會匯出為自訂屬性。 他們會在要求、相依性、追蹤或例外狀況數據表中填入 customDimensions 字段。

若要新增範圍屬性，請使用下列兩種方式之一：

  • 使用 工具庫提供的選項。
  • 新增自訂範圍處理器。

秘訣

使用檢測程式庫所提供的選項的優點 (如果有) 是整個上下文都可用。 因此，使用者可以選取要新增或篩選更多屬性。 例如，HttpClient 檢測連結庫中的擴充選項可讓使用者存取 HttpRequestMessage 和 HttpResponseMessage 本身。 使用者可以從中選取任何部分並儲存為屬性。

  1. 許多檢測程式庫都提供擴充選項。 如需指引，請參閱各個工具庫的讀我檔案。

  2. 使用自訂處理器：

    秘訣

    請在新增 Azure 監視器之前，先新增這裡顯示的處理器。

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

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));

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

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

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

    使用下列程式碼，將 ActivityEnrichingProcessor.cs 新增至您的專案：

    public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

設定使用者 IP

您可以透過在 span 上設定屬性，以填入請求的 client_IP 欄位。 Application Insights 會使用IP位址來產生使用者位置屬性，然後 依預設捨棄它。

使用 自訂屬性範例，但在 ActivityEnrichingProcessor.cs中取代以下程式碼行：

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IP Address>");

設定使用者識別碼或已驗證的使用者識別碼

您可以使用下列指引填入要求的 user_Id 或 user_AuthenticatedId 欄位。 使用者識別碼是匿名使用者識別碼。 已驗證的使用者識別碼是已知的使用者識別碼。

重要

在您設定已驗證的使用者識別碼之前，請參閱適用的隱私權法律。

使用 自訂屬性範例：

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<User Id>");

新增記錄屬性

OpenTelemetry 使用。NET 的 ILogger。 您可以使用 訊息範本將自訂維度附加至記錄。

取得追蹤識別碼或範圍識別碼

您可以使用下列步驟來取得目前使用中 Span 的 Trace ID 和 Span ID。

附註

Activity 命名空間中的 ActivitySource 和 System.Diagnostics 類別分別代表 OpenTelemetry 的 Span 和 Tracer 概念。 這是因為 OpenTelemetry 追蹤 API 的部分會直接併入 .NET 執行環境。 若要深入瞭解，請參閱 OpenTelemetry .NET 追蹤 API 簡介。

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

下一步

  • Last updated on