OpenTelemetry ekleme, değiştirme ve filtreleme

  • Makale

Bu makalede, Azure İzleyici Application Insights kullanarak uygulamalar için OpenTelemetry ekleme, değiştirme ve filtreleme hakkında yönergeler sağlanır.

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

Otomatik veri toplama

Dağıtımlar, OpenTelemetry izleme kitaplıklarını paketleyerek otomatik olarak veri toplar.

Dahil edilen izleme kitaplıkları

İstekler

Bağımlılıklar

Günlüğe kaydetme

  • ILogger

hakkında ILoggerdaha fazla bilgi için bkz . C# ve .NET'te günlüğe kaydetme ve kod örnekleri.

Dipnot

  • ¹: İşlenmeyen/yakalanmayan özel durumların otomatik raporlamayı destekler
  • ²: OpenTelemetry Ölçümlerini Destekler
  • ³: Günlük kaydı varsayılan olarak yalnızca BİlGİ düzeyinde veya daha yüksek bir düzeyde toplanır. Bu ayarı değiştirmek için yapılandırma seçeneklerine bakın.
  • ⁴: Varsayılan olarak, günlük yalnızca bu günlük UYARI düzeyinde veya daha yüksek bir düzeyde gerçekleştirildiğinde toplanır.

Not

Azure İzleyici OpenTelemetry Dağıtımları, Application Insights standart ölçümlerini otomatik olarak yaymak için özel eşleme ve mantık içerir.

İpucu

İzleme kitaplıklarından otomatik olarak toplanan veya özel kodlamadan el ile toplanan tüm OpenTelemetry ölçümleri şu anda faturalama amacıyla Application Insights "özel ölçümler" olarak kabul edilir. Daha fazla bilgi edinin.

Topluluk izleme kitaplığı ekleme

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, gönderi veya geri bildirim topluluğumuzda oy verme önerisinde bulunmak için. Bazıları deneysel OpenTelemetry belirtimlerini temel alır ve gelecekteki hataya neden olabilecek değişikliklere neden olabilir.

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

Aşağıdaki örnekte, çalışma zamanı izlemesinin ek ölçümler toplamak için nasıl eklenebilecekleri 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

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 İzlemeler
ASP.NET Core
   OpenTelemetry API'si Yes Evet Evet Yes
   ILogger UPA Yes
   AI Klasik API
Java
   OpenTelemetry API'si Yes Evet Evet Yes
   Logback, Log4j, JUL Yes Yes
   Micrometer ölçümleri Yes
   AI Klasik API Yes Evet Evet Evet Evet Evet Yes
Node.js
   OpenTelemetry API'si Yes Evet Evet Yes
Python
   OpenTelemetry API'si Yes Evet Evet Yes
   Python Günlük Modülü Yes
   Olay Uzantısı Yes Evet

Not

Application Insights Java 3.x, Application Insights Klasik API'sine gönderilen telemetri verilerini dinler. Benzer şekilde, Application Insights Node.js 3.x, Application Insights Klasik API'siyle oluşturulan olayları toplar. Bu, yükseltmeyi kolaylaştırır ve tüm özel telemetri türleri OpenTelemetry API'sini kullanarak desteklenene kadar özel telemetri desteğimizdeki boşluğu doldurur.

Özel ölçümler ekleme

Bu bağlamda özel ölçümler terimi, OpenTelemetry Instrumentation Kitaplıklarının otomatik olarak topladığı ölçümlerin ötesinde ek ölçümler toplamak için kodunuzu el ile izleme anlamına gelir.

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 Instrument Azure İzleyici Toplama Türü
Sayaç Sum
Zaman Uyumsuz Sayaç Sum
Histogram Min, Max, Average, Sum ve Count
Zaman Uyumsuz Ölçer Ortalama
UpDownCounter Sum
Zaman Uyumsuz UpDownCounter Sum

Dikkat

Tabloda gösterilenin ötesinde toplama türleri genellikle anlamlı değildir.

OpenTelemetry Belirtimi, 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 dönüştürmektedir ve yüzdebirlik değerler desteği devam ediyor. 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şlatma, bir Ölçüme ada göre abone olmalı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ı Meter ad kullanılarak 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"));

Sayaç örneği

Uygulama başlatma, bir Ölçüme ada göre abone olmalı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ı Meter ad kullanılarak 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şlatma, bir Ölçüme ada göre abone olmalı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ı Meter ad kullanılarak 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 özel durumlar ekleme

İzleme kitaplıklarını seçin ve özel durumları Application Insights'a otomatik olarak bildirin. Ancak, hangi izleme kitaplıkları raporu dışında özel durumları el ile raporlamak isteyebilirsiniz. Örneğin, kodunuz tarafından yakalanan özel durumlar normalde bildirilir. 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.

  • Etkinlik kullanarak bir Özel Durumu günlüğe kaydetmek iç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);
    }
}

  • kullanarak ILoggerbir Özel Durumu 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 yayılma alanları ekleme

İki senaryoda özel bir yayılma alanı 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 ad alanından System.Diagnostics ve ActivitySource sınıfları sırasıyla ve Tracer'nin Span OpenTelemetry kavramlarını temsil ediyor. doğrudan yerine oluşturucusunu kullanarak TracerProvideroluşturursunuzActivitySource. Her ActivitySource sınıf kullanılarak AddSource()açıkça bağlanmalıdırTracerProvider. 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 değeridir ActivityKind.Internal, ancak başka ActivityKindherhangi bir sağlayabilirsiniz. ActivityKind.Client, ActivityKind.Producerve ActivityKind.Internal Application Insights dependenciesile eşlenir. ActivityKind.Server ve ActivityKind.Consumer Application Insights requestsile eşlenir.

Application Insights Klasik API'sini kullanarak özel telemetri gönderme

Mümkün olduğunda OpenTelemetry API'lerini kullanmanızı öneririz, ancak Application Insights Klasik API'sini kullanmanız gereken bazı senaryolar olabilir.

Etkinlikler

  1. Uygulamanıza ekleyin Microsoft.ApplicationInsights .

  2. TelemetryClient Örnek oluşturma:

    Not

    Her uygulama için TelemetryClient örneğinin yalnızca bir kez oluşturulması önemlidir.

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

  3. Özel telemetri göndermek için istemciyi kullanın:

    telemetryClient.TrackEvent("testEvent");

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:

  • İzleme kitaplıkları tarafından sağlanan seçenekleri kullanın.
  • Özel bir span işlemcisi ekleyin.

İpucu

İzleme kitaplıkları tarafından sağlanan seçenekleri kullanmanın avantajı, kullanılabilir olduklarında bağlamın tamamının kullanılabilir 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'ın kendisine erişim verir. Herhangi bir öğeyi seçip bir öznitelik olarak depolayabilirler.

  1. Birçok izleme kitaplığı zenginleştirme seçeneği sunar. Yönergeler için, tek tek izleme kitaplıklarının benioku dosyalarına bakın:

  2. Özel işlemci kullanın:

    İpucu

    Azure İzleyici'yi 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();

    Aşağıdaki kodla projenize ekleyin 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");
    }
}

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 atar.

Ö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 kullanır. NET'in ILogger. Günlüklere özel boyutlar ekleme, bir ileti şablonu kullanılarak gerçekleştirilebilir.

Telemetri filtreleme

Telemetriyi uygulamanızdan çıkmadan önce filtrelemek için aşağıdaki yöntemleri kullanabilirsiniz.

  1. Birçok izleme kitaplığı bir filtre seçeneği sağlar. Yönergeler için, tek tek izleme kitaplıklarının benioku dosyalarına bakın:

  2. Özel işlemci kullanın:

    İpucu

    Azure İzleyici'yi 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 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();

    Aşağıdaki kodla projenize ekleyin 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. Belirli bir kaynak kullanılarak açıkça eklenmiyorsa, bu kaynak kullanılarak AddSource("ActivitySourceName")oluşturulan etkinliklerin hiçbiri dışarı aktarılamaz.

İzleme kimliğini veya yayılma kimliğini alma

Şu anda etkin olan Span'in ve'sini Span ID aşağıdaki adımları kullanarak edinebilirsinizTrace ID.

Not

Activity ad alanından System.Diagnostics ve ActivitySource sınıfları sırasıyla ve Tracer'nin Span OpenTelemetry kavramlarını temsil ediyor. 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ş.

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

Sonraki adımlar