共用方式為

新增、修改和篩選 OpenTelemetry

  • 發行項

本文提供如何使用 Azure 監視器 Application Insights 為應用程式新增、修改和篩選 OpenTelemetry 的指導。

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

自動收集資料

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

包含的檢測程式庫

要求

相依性

Logging

  • ILogger

如需 ILogger 的詳細資訊，請參閱使用 C# 和 .NET 進行記錄和程式碼範例。

註腳

  • ¹：支援自動報告未處理/未攔截的例外狀況
  • ²：支援 OpenTelemetry 計量
  • ³：根據預設，只會在 INFO 層級或更高層級收集記錄。 若要變更此層級，請參閱設定選項。
  • 根據預設，只有在 INFO 層級或警告層級執行記錄時，才會收集該記錄。

注意

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 API
  • 語言特定的記錄/計量程式庫
  • Application Insights 傳統 API

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

語言 自訂事件 自訂計量 相依性 例外狀況 頁面檢視 要求 追蹤
ASP.NET Core
   OpenTelemetry API Yes .是 .是 Yes
   ILogger API Yes
   AI 傳統 API
Java
   OpenTelemetry API Yes .是 .是 Yes
   Logback、Log4j、JUL Yes Yes
   Micrometer Metrics Yes
   AI 傳統 API Yes .是 .是 .是 .是 .是 Yes
Node.js
   OpenTelemetry API Yes .是 .是 Yes
Python
   OpenTelemetry API Yes .是 .是 Yes
   Python 記錄模組 Yes
   事件延伸模組 Yes 是

注意

Application Insights Java 3.x 會接聽傳送至 Application Insights 傳統 API 的遙測。 同樣地，Application Insights Node.js 3.x 會收集使用 Application Insights 傳統 API 建立的事件。 因此，升級更容易，而且自訂遙測支援的不足之處得以補強，直到全部自訂遙測類型都透過 OpenTelemetry API 支援為止。

新增自訂計量

在此內容中，自定義計量詞彙是指手動檢測您的程序代碼，以收集 OpenTelemetry Instrumentation 連結庫自動收集的其他計量。

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

下表顯示每個 OpenTelemetry 計量檢測的建議彙總類型。

OpenTelemetry 檢測 Azure 監視器彙總類型
計數器 Sum
非同步計數器 Sum
長條圖 Min、Max、Average、Sum 和 Count
非同步量測計 平均
UpDownCounter Sum
非同步 UpDownCounter Sum

警告

超出表格中所顯示內容的彙總類型通常沒有意義。

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

新增自訂範圍

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

注意

System.Diagnostics 命名空間中的 Activity 和 ActivitySource 類別分別代表 OpenTelemetry 的 Span 和 Tracer 概念。 您可以使用其建構函式直接建立 ActivitySource，而不是使用 TracerProvider。 每個 ActivitySource 類別都必須使用 AddSource() 明確連接到 TracerProvider。 這是因為部分 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 傳統 API 傳送自訂遙測

建議您盡可能使用 OpenTelemetry API，但在某些情況下，您必須使用 Application Insights 傳統 API。

活動

  1. 將 Microsoft.ApplicationInsights 新增至您的應用程式。

  2. 建立 TelemetryClient 執行個體：

    注意

    務必只為每個應用程式建立一次 TelemetryClient 執行個體。

    var telemetryConfiguration = new TelemetryConfiguration { ConnectionString = "" };
var telemetryClient = new TelemetryClient(telemetryConfiguration);

  3. 使用用戶端來傳送自訂遙測：

    telemetryClient.TrackEvent("testEvent");

修改遙測

本節說明如何修改遙測。

新增範圍屬性

這些屬性可能包括將自訂屬性新增至遙測。 您也可以使用屬性來設定 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

您可以設定範圍的屬性，以填入要求的 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。 您可以使用訊息範本將自訂維度附加至記錄。

篩選遙測

您可以使用下列方式，在遙測離開您的應用程式之前篩選出遙測資料。

  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 ActivityFilteringProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityFilteringProcessor()));
// Configure the OpenTelemetry tracer provider to add a new source named "ActivitySourceName".
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();

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

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

    public class ActivityFilteringProcessor : BaseProcessor<Activity>
{
    // The OnStart method is called when an activity is started. This is the ideal place to filter activities.
    public override void OnStart(Activity activity)
    {
        // prevents all exporters from exporting internal activities
        if (activity.Kind == ActivityKind.Internal)
        {
            activity.IsAllDataRequested = false;
        }
    }
}

  3. 如果未使用 AddSource("ActivitySourceName") 明確新增特定來源，則不會匯出使用該來源所建立的任何活動。

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

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

注意

System.Diagnostics 命名空間中的 Activity 和 ActivitySource 類別分別代表 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();

下一步