Menambahkan dan memodifikasi Azure Monitor OpenTelemetry untuk aplikasi .NET, Java, Node.js, dan Python

Panduan ini memberikan instruksi tentang mengintegrasikan dan menyesuaikan instrumentasi OpenTelemetry (OTel) dalam Azure Monitor Application Insights.

Untuk mempelajari selengkapnya tentang konsep OpenTelemetry, lihat gambaran umum OpenTelemetry.

Catatan

Untuk Azure Function Apps, lihat Gunakan OpenTelemetry dengan Azure Functions.

Menambahkan pustaka instrumentasi komunitas

Untuk gambaran umum semua pustaka instrumentasi yang disertakan dengan distro OpenTelemetry Azure Monitor, lihat Automatic data collection and resource detectors for Azure Monitor OpenTelemetry.

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 kami, posting atau beri suara di komunitas feedback kami. Perlu diketahui, beberapa didasarkan pada spesifikasi OpenTelemetry eksperimental dan mungkin memperkenalkan perubahan besar di masa depan.

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

Contoh berikut menunjukkan cara menambahkan Instrumentasi Runtime 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 (antarmuka pemrograman aplikasi OpenTelemetry)
  • Pustaka pencatatan/metrik khusus bahasa

Catatan

Micrometer Tracing API untuk Java tidak didukung.

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

Bahasa Peristiwa Kustom Metrik Khusus Dependensi Pengecualian Tampilan Halaman Permintaan Jejak
ASP.NET Core
   OpenTelemetry API (antarmuka pemrograman aplikasi OpenTelemetry) Ya Ya Ya Ya
    ILogger Antarmuka Pemrograman Aplikasi (API) Ya Ya
Java
   OpenTelemetry API (antarmuka pemrograman aplikasi OpenTelemetry) Ya Ya Ya Ya Ya
   Logback, Log4j, JUL Ya Ya
   Metrik Mikrometer Ya
Node.js
   OpenTelemetry API (antarmuka pemrograman aplikasi OpenTelemetry) Ya Ya Ya Ya Ya
Python
   OpenTelemetry API (antarmuka pemrograman aplikasi OpenTelemetry) Ya Ya Ya Ya
   Modul Pengelogan Python Ya
   Ekstensi Peristiwa Ya Ya

Menambahkan metrik kustom

Dalam konteks ini, istilah metrik khusus merujuk pada proses menambahkan instrumen secara manual ke dalam kode Anda untuk mengumpulkan metrik tambahan, melampaui apa yang secara otomatis dikumpulkan oleh OpenTelemetry Instrumentation Libraries. Untuk mempelajari selengkapnya tentang menggunakan metrik, lihat Metrik di Application Insights.

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
PenghitungNaikTurun Asinkron Jumlah total

Perhatian

Jenis agregasi lainnya tidak bermakna dalam banyak kasus.

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

Tips

Histogram adalah instrumen metrik OpenTelemetry paling serbaguna untuk merekam distribusi. 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 efek 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 pengecualian

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

Pustaka instrumentasi yang dipilih secara otomatis melaporkan pengecualian ke Application Insights. Namun, Anda mungkin ingin melaporkan pengecualian secara manual selain dari apa yang dilaporkan oleh pustaka instrumentasi. Misalnya, pengecualian yang ditangkap oleh kode Anda biasanya tidak dilaporkan. Anda mungkin ingin melaporkannya untuk menarik perhatian dalam pengalaman terkait, termasuk di bagian kegagalan dan pandangan transaksi menyeluruh.

  • 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 pandangan transaksi menyeluruh.

Catatan

Kelas Activity dan ActivitySource dari namespace System.Diagnostics, masing-masing menggambarkan konsep OpenTelemetry dari Span dan Tracer. Anda membuat ActivitySource secara langsung dengan menggunakan konstruktornya daripada menggunakan TracerProvider. Setiap kelas ActivitySource harus secara eksplisit terhubung ke TracerProvider dengan menggunakan AddSource(). Ini karena bagian dari API pelacakan OpenTelemetry dimasukkan langsung ke dalam runtime .NET. Untuk mempelajari lebih lanjut, lihat Introduction ke OpenTelemetry .NET Tracing 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 berfungsi sebagai bawaan ke ActivityKind.Internal, tetapi Anda dapat memberikan nilai lain ActivityKind. ActivityKind.Client, ActivityKind.Producer, dan ActivityKind.Internal dipetakan ke Application Insights dependencies. ActivityKind.Server dan ActivityKind.Consumer dipetakan ke Application Insights requests.

Kirim peristiwa kustom

Application Insights menyimpan peristiwa kustom dalam customEvents tabel. Salah satu cara untuk menganalisis, memfilter, dan memvisualisasikannya adalah dengan menggunakan pengalaman penggunaan Application Insights.

Jika Anda ingin mengotomatiskan pengumpulan peristiwa interaksi sisi klien, Anda dapat menggunakan plugin di JavaScript SDK.

Peristiwa kustom menggunakan Azure.Monitor.OpenTelemetry.AspNetCore.

Untuk mengirim CustomEvent menggunakan ILogger, atur "microsoft.custom_event.name" atribut dalam templat pesan.

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

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 ke rentang diekspor sebagai properti kustom. Mereka mengisi kolom customDimensions dalam tabel yang berisi permintaan, jejak, pengecualian, atau dependensi.

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

Tips

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 access ke HttpRequestMessage dan HttpResponseMessage itu sendiri. Mereka dapat memilih apa pun darinya dan menyimpannya sebagai atribut.

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

  2. Gunakan prosesor kustom:

    Tips

    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 ke project Anda dengan kode berikut:

    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 lalu 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 ILogger. Melampirkan dimensi kustom ke log bisa dilakukan menggunakan templat pesan.

Mengesampingkan status kesalahan permintaan untuk respons HTTP 4xx

Anda dapat mencegah Application Insights menghitung respons 4xx sebagai kesalahan.

Kode berikut menunjukkan prosesor aktivitas kustom yang menandai respons HTTP 4xx sebagai berhasil.

Prosesor:

public class Http4xxSuccessProcessor : BaseProcessor<Activity>
{
	public override void OnEnd(Activity activity)
	{
		if (activity.Kind == ActivityKind.Server)
		{
			var statusCodeTag = activity.GetTagItem("http.response.status_code");
			if (statusCodeTag is int statusCode && statusCode >= 400 && statusCode < 500)
			{
				// Set status to Ok to bypass the Azure Monitor exporter's default logic
				// which treats any HTTP 4xx as failure when status is Unset.
				// The response code tag (e.g., 400) remains unchanged — only the
				// success field in Application Insights is affected.
				activity.SetStatus(ActivityStatusCode.Ok);
			}
		}

		base.OnEnd(activity);
	}
}

Pendaftaran:

builder.Services.AddOpenTelemetry()
	.UseAzureMonitor(options =>
	{
		options.ConnectionString = "<your-connection-string>";
	})
	.WithTracing(tracing =>
	{
		// Add custom processor to mark 4xx responses as successful
		tracing.AddProcessor<Http4xxSuccessProcessor>();
	});

Dapatkan ID jejak atau ID rentang

Dapatkan Trace ID dan Span ID untuk rentang yang aktif saat ini dengan menggunakan langkah-langkah berikut.

Catatan

Kelas Activity dan ActivitySource dari namespace System.Diagnostics, masing-masing menggambarkan konsep OpenTelemetry dari Span dan Tracer. Ini karena bagian dari API pelacakan OpenTelemetry dimasukkan langsung ke dalam runtime .NET. Untuk mempelajari lebih lanjut, lihat Introduction ke OpenTelemetry .NET Tracing 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();

Pemecahan masalah, umpan balik, dan dukungan

Tips

Bagian berikut tersedia di semua artikel Distro OpenTelemetry.

Troubleshooting

Umpan Balik OpenTelemetry

Untuk memberikan umpan balik:

Support

Pilih tab untuk bahasa pilihan Anda untuk menemukan opsi dukungan.

  • Untuk masalah Azure support, buka tiket Azure support.
  • Untuk masalah OpenTelemetry, hubungi komunitas OpenTelemetry .NET secara langsung.
  • Untuk daftar masalah terbuka yang terkait dengan pengekspor Azure Monitor, lihat Halaman Masalah GitHub.

Langkah berikutnya

  • Last updated on