Aracılığıyla paylaş

Azure İzleyici OpenTelemetry'yi .NET, Java, Node.js ve Python uygulamaları için ekleyin ve değiştirin.

Bu kılavuz, Azure İzleyici Application Insights kapsamında OpenTelemetry (OTel) araçlarını entegre etme ve özelleştirmeye yönelik talimatlar sağlar.

OpenTelemetry kavramları hakkında daha fazla bilgi edinmek için bkz. OpenTelemetry'ye genel bakış.

Not

Azure İşlev Uygulamaları için bkz. Azure İşlevleri ile OpenTelemetry kullanma.

Topluluk izleme kitaplığı ekleme

Azure İzleyici OpenTelemetry dağıtımına dahil edilen tüm izleme kitaplıklarına genel bakış için Azure İzleyici OpenTelemetry için Otomatik veri toplama ve kaynak algılayıcıları başlığına bakın.

OpenTelemetry topluluğundan izleme kitaplıkları eklediğinizde otomatik olarak daha fazla veri toplayabilirsiniz.

Dikkat

Topluluk izleme kitaplıklarının kalitesini desteklemiyoruz veya garanti vermiyoruz. Dağıtımımız için bir öneride bulunmak için, geri bildirim topluluğumuzda gönderi yapın veya oy verin. Deneysel OpenTelemetry belirtimlerini temel alan bazı durumların, gelecekte uyumsuzluklara yol açabilecek değişiklikler içerebileceğini unutmayın.

Topluluk kitaplığı eklemek için, kitaplığın NuGet paketini ekledikten sonra ConfigureOpenTelemetryMeterProvider veya ConfigureOpenTelemetryTracerProvider yöntemlerini kullanın.

Aşağıdaki örnekte, ek ölçümler toplamak için Çalışma Zamanı İzlemesi'nin nasıl ekleneceği gösterilmektedir:

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

Özel telemetri toplama

Bu bölümde, uygulamanızdan özel telemetri verilerinin nasıl toplayacağınız açıklanmaktadır.

Dilinize ve sinyal türünüze bağlı olarak, özel telemetri toplamanın farklı yolları vardır, örneğin:

  • OpenTelemetry API'si
  • Dile özgü günlük/ölçüm kitaplıkları
  • Application Insights Klasik API'si

Not

Java için Micrometer İzleme API desteklenmemektedir.

Aşağıdaki tablo, şu anda desteklenen özel telemetri türlerini temsil eder:

Dil Özel Olaylar Özel Ölçümler Bağımlılıklar Özel durumlar Sayfa Görünümleri İstekler İzler
ASP.NET Core
   OpenTelemetry API'si Evet Evet Evet Evet
    ILogger API (Uygulama Programlama Arayüzü) Evet Evet
   AI Klasik API Evet
Java
   OpenTelemetry API'si Evet Evet Evet Evet Evet
   Logback, Log4j, JUL Evet Evet
   Mikrometre Özellikleri Evet
   AI Klasik API Evet Evet Evet Evet Evet Evet Evet
Node.js
   OpenTelemetry API'si Evet Evet Evet Evet Evet
Python
   OpenTelemetry API'si Evet Evet Evet Evet
   Python Günlüğü Modülü Evet
   Etkinlik Eklentisi Evet Evet

Not

Application Insights Java 3.x ve Application Insights Node.js 3.x, Application Insights Classic API telemetri verilerini toplar. Bu davranış, OpenTelemetry API'sinde tüm özel telemetri türleri bulunana kadar yükseltmeleri basitleştirir ve geçici olarak özel telemetriyi destekler.

Özel ölçümler ekleme

Bu bağlamda, özel metrikler terimi, OpenTelemetry İzleme Kitaplıklarının otomatik olarak topladıklarının ötesinde ek metrikler toplamak için kodunuzu manuel olarak izlemeye atıfta bulunur. Ölçümleri kullanma hakkında daha fazla bilgi edinmek için bkz. Application Insights'ta Ölçümler.

OpenTelemetry API'si, çeşitli ölçüm senaryolarını kapsayacak altı ölçüm "aracı" sunar ve Ölçüm Gezgini'nde ölçümleri görselleştirirken doğru "Toplama Türü"nü seçmeniz gerekir. Bu gereksinim, ölçümleri göndermek için OpenTelemetry Ölçüm API'sini kullanırken ve bir izleme kitaplığı kullanırken geçerlidir.

Aşağıdaki tabloda OpenTelemetry Ölçüm Araçlarının her biri için önerilen toplama türleri gösterilmektedir.

OpenTelemetry Enstrüman Azure İzleyici Toplama Türü
Sayaç Toplam
Asenkron Sayaç Toplam
Histogram Grafiği Minimum, Maksimum, Ortalama, Toplam ve Sayı
Zaman Uyumsuz Ölçer Ortalama
UpDownCounter Toplam
Zaman Uyumsuz UpDownCounter Toplam

Dikkat

Diğer toplama türleri çoğu durumda anlamlı değildir.

OpenTelemetry Specification araçları açıklar ve her birini ne zaman kullanabileceğinize ilişkin örnekler sağlar.

İpucu

Histogram, Application Insights GetMetric Klasik API'sinin en çok yönlü ve en yakın eşdeğeridir. Azure İzleyici şu anda histogram aracını, desteklenen beş toplama türüne göre düzleştirir ve yüzde değerleri için destek sağlanması devam etmektedir. Daha az çok yönlü olsa da, diğer OpenTelemetry araçları uygulamanızın performansı üzerinde daha az etkiye sahiptir.

Histogram örneği

Uygulama başlatılırken, bir Ölçüme adıyla abone olunmalıdır.

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

Aynı adla Meter başlatılmalıdır.

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

Karşıt örnek

Uygulama başlatılırken, bir Ölçüme adıyla abone olunmalıdır.

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

Aynı adla Meter başlatılmalıdır.

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

Ölçer örneği

Uygulama başlatılırken, bir Ölçüme adıyla abone olunmalıdır.

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

Aynı adla Meter başlatılmalıdır.

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

Özel durumlar ekleme

Seçilen izleme kitaplıkları, özel durumları Application Insights'a otomatik olarak bildirir. Ancak, enstrümantasyon kütüphanelerinin raporladıklarının ötesinde istisnaları el ile raporlamak isteyebilirsiniz. Örneğin, kodunuz tarafından yakalanan özel durumlar normalde bildirilmez. Hataların bölümü ve uçtan uca işlem görünümleri de dahil olmak üzere ilgili deneyimlerde dikkat çekmek için bunları raporlamak isteyebilirsiniz.

  • Bir Etkinlik Kullanarak Bir İstisna Kaydetmek İçin:

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

  • Bir Özel Durumu, kullanarak günlüğe kaydetmek için:

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

Özel aralıklar ekleme

İki senaryoda özel bir aralık eklemek isteyebilirsiniz. İlk olarak, izleme kitaplığı tarafından henüz toplanmamış bir bağımlılık isteği olduğunda. İkincisi, bir uygulama işlemini uçtan uca işlem görünümünde bir yayılma alanı olarak modellemek istediğinizde.

Not

Activity ve ActivitySource sınıfları, sırasıyla, System.Diagnostics ad alanından Span ve Tracer OpenTelemetry kavramlarını temsil eder. ActivitySource, TracerProvider yerine doğrudan yapıcı fonksiyonunu kullanarak oluşturursunuz. Her ActivitySource sınıfı, TracerProvider kullanılarak açıkça AddSource() bağlanmalıdır. Bunun nedeni OpenTelemetry izleme API'sinin bölümlerinin doğrudan .NET çalışma zamanına dahil edilmiş olmasıdır. Daha fazla bilgi edinmek için bkz. OpenTelemetry .NET İzleme API'sine Giriş.

// 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 varsayılan olarak ActivityKind.Internal'dir, ancak başka herhangi bir ActivityKind sağlayabilirsiniz. ActivityKind.Client, ActivityKind.Producerve ActivityKind.Internal Application Insights dependenciesile eşlenir. ActivityKind.Server ve ActivityKind.Consumer Application Insights requests ile eşlenir.

Özel olaylar gönderme

Application Insights özel olayları customEvents tabloda depolar. Bunları analiz etmenin , filtrelemenin ve görselleştirmenin bir yolu , Application Insights kullanım deneyimlerini kullanmaktır.

İstemci tarafı etkileşim olaylarının koleksiyonunu otomatikleştirmek istiyorsanız JavaScript SDK'sında eklentiyi kullanabilirsiniz.

Özel olaylar Azure.Monitor.OpenTelemetry.AspNetCore kullanır.

Bir CustomEvent göndermek için ILogger kullanarak, ileti şablonunda "microsoft.custom_event.name" özelliğini ayarlayın.

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

Telemetriyi değiştirme

Bu bölümde telemetrinin nasıl değiştirileceği açıklanmaktadır.

Span öznitelikleri ekleme

Bu öznitelikler telemetrinize özel özellik eklemeyi içerebilir. Application Insights şemasında İstemci IP'leri gibi isteğe bağlı alanlar ayarlamak için öznitelikleri de kullanabilirsiniz.

Span'a özel özellik ekleme

Span'lara eklediğiniz tüm öznitelikler özel özellikler olarak dışarı aktarılır. İstekler, bağımlılıklar, izlemeler veya özel durumlar tablosunda customDimensions alanını doldurur.

Span öznitelikleri eklemek için aşağıdaki iki yoldan birini kullanın:

İpucu

İzleme araçları kitaplıkları tarafından sağlanan seçenekleri kullanmanın avantajı, bunlar mevcut olduğunda tüm bağlamın erişilebilir olmasıdır. Sonuç olarak, kullanıcılar daha fazla öznitelik eklemeyi veya filtrelemeyi seçebilir. Örneğin, HttpClient izleme kitaplığındaki zenginleştirme seçeneği, kullanıcılara HttpRequestMessage ve HttpResponseMessage üzerinde erişim imkanı tanır. Herhangi bir öğeyi seçip bir öznitelik olarak depolayabilirler.

  1. Birçok araçsal kütüphane zenginleştirme seçeneği sunar. Yönergeler için, her bir araç oluşturma kitaplığının readme dosyalarına bakın:

  2. Özel işlemci kullanın:

    İpucu

    Azure İzleyici'ü eklemeden önce burada gösterilen işlemciyi ekleyin.

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

    Projenize aşağıdaki kodla ActivityEnrichingProcessor.cs ekleyin:

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

Kullanıcı IP'sini ayarlama

span üzerinde bir öznitelik ayarlayarak istekler için client_IP alanını doldurabilirsiniz. Application Insights, kullanıcı konumu öznitelikleri oluşturmak için IP adresini kullanır ve varsayılan olarak siler.

Özel özellik örneğini kullanın, ancak içindeki ActivityEnrichingProcessor.csaşağıdaki kod satırlarını değiştirin:

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

Kullanıcı kimliğini veya kimliği doğrulanmış kullanıcı kimliğini ayarlama

aşağıdaki kılavuzu kullanarak istekler için user_Id veya user_AuthenticatedId alanını doldurabilirsiniz. Kullanıcı kimliği anonim bir kullanıcı tanımlayıcısıdır. Kimliği doğrulanmış Kullanıcı Kimliği bilinen bir kullanıcı tanımlayıcısıdır.

Önemli

Kimliği Doğrulanmış Kullanıcı Kimliği'ni ayarlamadan önce geçerli gizlilik yasalarına başvurun.

Özel özellik örneğini kullanın:

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

Günlük öznitelikleri ekleme

OpenTelemetry, .NET ILogger kullanır. Günlüklere özel boyutlar ekleme, bir ileti şablonu kullanılarak gerçekleştirilebilir.

HTTP 4xx yanıtları için geçersiz kılma isteği hata durumu

Application Insights'ın 4xx yanıtları hata olarak saymasını engelleyebilirsiniz.

Aşağıdaki kod, HTTP 4xx yanıtlarını başarılı olarak işaretleyen özel bir etkinlik işlemcisini gösterir.

Işlemci:

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

Kayıt:

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

İzleme kimliğini veya span kimliğini alma

Aşağıdaki adımları kullanarak geçerli etkin yayılma alanı için Trace ID ve Span ID alın.

Not

Activity ve ActivitySource sınıfları, sırasıyla, System.Diagnostics ad alanından Span ve Tracer OpenTelemetry kavramlarını temsil eder. Bunun nedeni OpenTelemetry izleme API'sinin bölümlerinin doğrudan .NET çalışma zamanına dahil edilmiş olmasıdır. Daha fazla bilgi edinmek için bakınız OpenTelemetry .NET İzleme API'sine Giriş.

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

Sorun giderme, geri bildirim ve destek

İpucu

Aşağıdaki bölümler tüm OpenTelemetry Distro makalelerinde kullanılabilir.

Sorun giderme

OpenTelemetry Geri Bildirimi

Geri bildirim sağlamak için:

Support

Destek seçeneklerini keşfetmek için istediğiniz dil için bir sekme seçin.

Sonraki adımlar

  • Last updated on