Bagikan melalui

Menambahkan, memodifikasi, dan memfilter OpenTelemetry

  • Artikel

Artikel ini menyediakan panduan tentang cara menambahkan, memodifikasi, dan memfilter OpenTelemetry untuk aplikasi menggunakan Azure Monitor Application Insights.

Untuk mempelajari selengkapnya tentang konsep OpenTelemetry, lihat Ringkasan OpenTelemetry atau Tanya Jawab Umum OpenTelemetry.

Pengumpulan data otomatis

Distro secara otomatis mengumpulkan data dengan menggabungkan pustaka instrumentasi OpenTelemetry.

Pustaka instrumentasi yang disertakan

Permintaan

Dependensi

Pembuatan Log

  • ILogger

Untuk informasi selengkapnya tentang ILogger, lihat Pengelogan dalam contoh C# dan .NET dan kode.

Catatan kaki

  • ¹: Mendukung pelaporan otomatis pengecualian yang tidak tertangani/tidak tertangani
  • ²: Mendukung Metrik OpenTelemetry
  • ³: Secara default, pengelogan hanya dikumpulkan pada tingkat INFO atau yang lebih tinggi. Untuk mengubah pengaturan ini, lihat opsi konfigurasi.
  • ⁴: Secara default, pengelogan hanya dikumpulkan ketika pengelogan tersebut dilakukan pada tingkat PERINGATAN atau yang lebih tinggi.

Catatan

Distro OpenTelemetry Azure Monitor mencakup pemetaan dan logika kustom untuk memancarkan metrik standar Application Insights secara otomatis.

Tip

Semua metrik OpenTelemetry baik yang dikumpulkan secara otomatis dari pustaka instrumentasi atau dikumpulkan secara manual dari pengodean kustom saat ini dianggap sebagai "metrik kustom" Application Insights untuk tujuan penagihan. Pelajari selengkapnya.

Menambahkan pustaka instrumentasi komunitas

Anda dapat mengumpulkan lebih banyak data secara otomatis saat menyertakan pustaka instrumentasi dari komunitas OpenTelemetry.

Perhatian

Kami tidak mendukung atau menjamin kualitas pustaka instrumentasi komunitas. Untuk menyarankan satu untuk distro, posting, atau up-vote kami di komunitas umpan balik kami. Perlu diketahui, beberapa didasarkan pada spesifikasi OpenTelemetry eksperimental dan mungkin memperkenalkan perubahan yang melanggar di masa depan.

Untuk menambahkan pustaka komunitas, gunakan ConfigureOpenTelemetryMeterProvider metode atau ConfigureOpenTelemetryTracerProvider , setelah menambahkan paket NuGet untuk pustaka.

Contoh berikut menunjukkan bagaimana Instrumentasi Runtime dapat ditambahkan untuk mengumpulkan metrik tambahan:

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();

Mengumpulkan telemetri kustom

Bagian ini menjelaskan cara mengumpulkan telemetri kustom dari aplikasi Anda.

Bergantung pada bahasa dan jenis sinyal Anda, ada berbagai cara untuk mengumpulkan telemetri kustom, termasuk:

  • OpenTelemetry API
  • Pustaka pengelogan/metrik khusus bahasa
  • API Klasik Application Insights

Tabel berikut ini mewakili jenis telemetri kustom yang saat ini didukung:

Bahasa Peristiwa Kustom Metrik Kustom Dependensi Pengecualian Tampilan Halaman Permintaan Jejak
Inti ASP.NET
   OpenTelemetry API Ya Ya Ya Ya
   ILogger API Ya
   API Klasik AI
Java
   OpenTelemetry API Ya Ya Ya Ya
   Logback, Log4j, JUL Ya Ya
   Metrik Mikrometer Ya
   API Klasik AI Ya Ya Ya Ya Ya Ya Ya
Node.js
   OpenTelemetry API Ya Ya Ya Ya
Python
   OpenTelemetry API Ya Ya Ya Ya
   Modul Pengelogan Python Ya
   Ekstensi Peristiwa Ya Ya

Catatan

Application Insights Java 3.x mendengarkan telemetri yang dikirim ke API Application Insights Classic. Demikian pula, Application Insights Node.js 3.x mengumpulkan peristiwa yang dibuat dengan API Klasik Application Insights. Ini membuat peningkatan lebih mudah dan mengisi kesenjangan dalam dukungan telemetri kustom kami sampai semua jenis telemetri kustom didukung melalui API OpenTelemetry.

Menambahkan metrik kustom

Dalam konteks ini, istilah metrik kustom mengacu pada instrumen kode Anda secara manual untuk mengumpulkan metrik tambahan di luar apa yang dikumpulkan pustaka Instrumentasi OpenTelemetry secara otomatis.

API OpenTelemetry menawarkan enam metrik "instrumen" untuk mencakup berbagai skenario metrik dan Anda perlu memilih "Jenis Agregasi" yang benar saat memvisualisasikan metrik di Metrics Explorer. Persyaratan ini berlaku saat menggunakan API Metrik OpenTelemetry untuk mengirim metrik dan saat menggunakan pustaka instrumentasi.

Tabel berikut menunjukkan jenis agregasi yang direkomendasikan untuk setiap Instrumen Metrik OpenTelemetry.

Instrumen OpenTelemetry Jenis Agregasi Azure Monitor
Penghitung Jumlah total
Penghitung Asinkron Jumlah total
Histogram Min, Maks, Rata-rata, Jumlah, dan Hitungan
Pengukur Asinkron Tengah
UpDownCounter Jumlah total
UpDownCounter Asinkron Jumlah total

Perhatian

Jenis agregasi di luar apa yang ditunjukkan dalam tabel biasanya tidak bermakna.

Spesifikasi OpenTelemetry menjelaskan instrumen dan memberikan contoh kapan Anda dapat menggunakan masing-masing instrumen.

Tip

Histogram adalah yang paling serbaguna dan paling setara dengan API Application Insights GetMetric Classic. Azure Monitor saat ini meratakan instrumen histogram ke dalam lima jenis agregasi yang didukung, dan dukungan untuk persentil sedang berlangsung. Meskipun kurang serbaguna, instrumen OpenTelemetry lainnya memiliki dampak yang lebih rendah pada performa aplikasi Anda.

Contoh histogram

Startup aplikasi harus berlangganan Meter menurut nama:

// 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 harus diinisialisasi menggunakan nama yang sama:

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

Contoh penghitung

Startup aplikasi harus berlangganan Meter menurut nama:

// 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 harus diinisialisasi menggunakan nama yang sama:

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

Contoh pengukur

Startup aplikasi harus berlangganan Meter menurut nama:

// 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 harus diinisialisasi menggunakan nama yang sama:

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

Menambahkan pengecualian kustom

Pilih pustaka instrumentasi secara otomatis melaporkan pengecualian ke Application Insights. Namun, Anda mungkin ingin melaporkan pengecualian secara manual di luar laporan pustaka instrumentasi. Misalnya, pengecualian yang ditangkap oleh kode Anda biasanya tidak dilaporkan. Anda mungkin ingin melaporkannya untuk menarik perhatian dalam pengalaman yang relevan termasuk bagian kegagalan dan tampilan transaksi end-to-end.

  • Untuk mencatat Pengecualian menggunakan Aktivitas:

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

  • Untuk mencatat Pengecualian menggunakan 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" });
}

Menambahkan rentang kustom

Anda mungkin ingin menambahkan rentang kustom dalam dua skenario. Pertama, ketika ada permintaan dependensi yang belum dikumpulkan oleh pustaka instrumentasi. Kedua, ketika Anda ingin memodelkan proses aplikasi sebagai rentang pada tampilan transaksi end-to-end.

Catatan

Kelas Activity dan ActivitySource dari namespace layanan System.Diagnostics, masing-masing mewakili konsep OpenTelemetry dari Span dan Tracer. Anda membuat ActivitySource secara langsung dengan menggunakan konstruktornya daripada menggunakan TracerProvider. Setiap ActivitySource kelas harus tersambung secara eksplisit TracerProvider dengan menggunakan AddSource(). Hal itu karena bagian dari OpenTelemetry yang melacak API dimasukkan secara langsung ke dalam runtime bahasa umum .NET. Untuk mempelajari selengkapnya, lihat Pengenalan API Pelacakan OpenTelemetry .NET.

// 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 default ke ActivityKind.Internal, tetapi Anda dapat menyediakan yang lain ActivityKind. ActivityKind.Client, ActivityKind.Producer, dan ActivityKind.Internal dipetakan ke Application Insights dependencies. ActivityKind.Server dan ActivityKind.Consumer dipetakan ke Application Insights requests.

Mengirim telemetri kustom menggunakan API Klasik Application Insights

Sebaiknya gunakan API OpenTelemetry jika memungkinkan, tetapi mungkin ada beberapa skenario saat Anda harus menggunakan API Klasik Application Insights.

Peristiwa

  1. Tambahkan Microsoft.ApplicationInsights ke aplikasi Anda.

  2. Buat contoh TelemetryClient:

    Catatan

    Penting untuk hanya membuat satu kali instans TelemetryClient per aplikasi.

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

  3. Gunakan klien untuk mengirim telemetri kustom:

    telemetryClient.TrackEvent("testEvent");

Mengubah telemetri

Bagian ini menjelaskan cara memodifikasi telemetri.

Menambahkan atribut rentang

Atribut ini mungkin menambahkan properti kustom ke telemetri Anda. Anda mungkin juga menggunakan atribut untuk mengatur bidang opsional dalam Skema Application Insights seperti IP Klien.

Menambahkan properti kustom ke Rentang

Atribut apa pun yang Anda tambahkan kepada rentang diekspor sebagai properti kustom. Mereka mengisi bidang customDimensions dalam tabel permintaan, dependensi, jejak, atau pengecualian.

Untuk menambahkan atribut rentang, gunakan salah satu dari dua cara berikut ini:

Tip

Keuntungan menggunakan opsi yang disediakan oleh pustaka instrumentasi, ketika opsi tersebut ada, yaitu tersedianya seluruh konteks. Sebagai hasilnya, pengguna dapat memilih untuk menambahkan atau memfilter lebih banyak atribut. Misalnya, opsi pengayaan di pustaka instrumentasi HttpClient memberi pengguna akses ke HttpRequestMessage dan HttpResponseMessage itu sendiri. Mereka dapat memilih apa pun darinya dan menyimpannya sebagai atribut.

  1. Banyak perpustakaan instrumentasi memberikan opsi yang dapat memperkaya. Sebagai panduan, lihat file readme dari pustaka instrumentasi individual:

  2. Gunakan prosesor kustom:

    Tip

    Tambahkan prosesor yang ditampilkan di sini sebelum menambahkan Azure Monitor.

    // 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();

    Tambahkan ActivityEnrichingProcessor.cs kode berikut ke proyek Anda:

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

Mengatur IP pengguna

Anda dapat mengisi bidang client_IP untuk permintaan dengan mengatur atribut pada rentang. Application Insights menggunakan alamat IP untuk menghasilkan atribut lokasi pengguna dan kemudian membuangnya secara default.

Gunakan contoh properti kustom, tetapi ganti baris kode berikut di 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>");

Mengatur ID pengguna atau ID pengguna terautentikasi

Anda dapat mengisi bidang user_Id atau user_AuthenticatedId untuk permintaan dengan menggunakan panduan berikut. ID pengguna adalah pengidentifikasi pengguna anonim. ID Pengguna Terautentikasi adalah pengidentifikasi pengguna yang diketahui.

Penting

Lihat undang-undang privasi yang berlaku sebelum Anda menetapkan ID Pengguna Terautentikasi.

Gunakan contoh properti kustom:

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

Menambahkan atribut log

OpenTelemetry menggunakan . NET' s ILogger. Melampirkan dimensi kustom ke log dapat dicapai menggunakan templat pesan.

Filter telemetri

Anda dapat menggunakan cara-cara berikut untuk menyaring telemetri sebelum meninggalkan aplikasi Anda.

  1. Banyak pustaka instrumentasi menyediakan opsi filter. Sebagai panduan, lihat file readme dari pustaka instrumentasi individual:

  2. Gunakan prosesor kustom:

    Tip

    Tambahkan prosesor yang ditampilkan di sini sebelum menambahkan Azure Monitor.

    // 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();

    Tambahkan ActivityFilteringProcessor.cs kode berikut ke proyek Anda:

    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. Jika sumber tertentu tidak ditambahkan secara eksplisit dengan menggunakan AddSource("ActivitySourceName"), maka tidak ada aktivitas yang dibuat dengan menggunakan sumber tersebut yang diekspor.

Dapatkan ID jejak atau ID rentang

Anda bisa mendapatkan Trace ID dan Span ID rentang yang saat ini aktif menggunakan langkah-langkah berikut.

Catatan

Kelas Activity dan ActivitySource dari namespace layanan System.Diagnostics, masing-masing mewakili konsep OpenTelemetry dari Span dan Tracer. Hal itu karena bagian dari OpenTelemetry yang melacak API dimasukkan secara langsung ke dalam runtime bahasa umum .NET. Untuk mempelajari selengkapnya, lihat Pengenalan API Pelacakan OpenTelemetry .NET.

// 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();

Langkah berikutnya