.NET'de dağıtılmış izlemeyi yapılandırma

.NET 11 ve sonraki sürümlerde, Microsoft.Extensions.Diagnostics.Tracing API'leri ActivitySource örneklerini kaydetmenize ve her dinleyicinin alacağı ActivityListener ve Activity örneklerini seçmek için kuralları kullanmanıza olanak tanır. Kodda kurallar tanımlayın veya bunları IConfiguration içinden yükleyin.

Important

İzleme kuralları yalnızca bu izleme altyapısı aracılığıyla kaydedilen dinleyicileri etkiler. Bunlar, telemetri dışa aktarıcılarının oluşturduğu ve yönettiği dinleyiciler de dahil olmak üzere ilgisiz ActivityListener örnekleri etkilemez. Bu dinleyicileri veya dışa aktarıcıları ayrı ayrı yapılandırın.

İzleme kaydı

API'ler Microsoft.Extensions.Diagnostics paketinde kullanılabilir. Microsoft.AspNetCore.App paylaşılan çerçevesine başvuran uygulamalar zaten derlemeyi içerir.

Bir AddTracing üzerinde IServiceCollection çağrısı yapın. Geri çağırmada:

Her dinleyiciyi kaydetmek için AddListener numarasını arayın. Dinleyici adı, yapılandırma kurallarında dinleyiciyi tanımlar.
Dinleyicinin örnekleme ve bildirim temsilcilerini ActivityListenerBuilder aracılığıyla yapılandırın. İzleme altyapısı ShouldListenTo, kaynak abonelikleri ve dinleyici ömrüne sahiptir.
Kuralları içeren yapılandırma bölümüyle AddConfiguration çağrısını yapın. Tracing adlı bir bölüm için configuration.GetSection("Tracing") parametresini iletin.

Tam örnek üç çağrıyı da gösterir. .NET konağı, konak başlatıldığında izleme aboneliklerini etkinleştirir. Host olmadan dependency injection'ı kullanıyorsanız, dinleyicileri oluşturmak ve aboneliklerini etkinleştirmek için kayıtlı ActivitySourceFactory öğesini çözümleyin. Tam örnek, factory’yi doğrudan çözümleyerek alır.

İzlemeyi yapılandır

Yapılandırma aracılığıyla veya kodda izleme kuralları ayarlayın. Bir dinleyici, kaynak, işlem ve kapsamla eşleşen bir kural yoksa, izleme bu birleşim için devre dışı kalır.

kod olmadan izlemeyi yapılandırma

Yapılandırma kullanan uygulamalar için Tracing dosyasına veya başka bir yapılandırma sağlayıcısına bölüm ekleyin. Ardından bu bölümü AddConfiguration öğesine aktarın:

tracing.AddConfiguration(configuration.GetSection("Tracing"));

Aşağıdaki örnekte desteklenen kural bölümleri ve kural düzeyleri gösterilmektedir:

{
  "Tracing": {
    "EnabledTracing": {
      "Default": false,
      "Contoso": true,
      "Contoso.Orders": {
        "Default": true,
        "HealthCheck": false
      },
      "Contoso.*.Storage": true
    },
    "EnabledGlobalTracing": {
      "System.Net.Http": true
    },
    "EnabledLocalTracing": {
      "Contoso.Workers": true
    },
    "Console": {
      "EnabledLocalTracing": {
        "Contoso.Orders": {
          "Submit": false
        }
      }
    }
  }
}

Kuralları doğrudan bir EnabledTracing, EnabledGlobalTracingveya EnabledLocalTracing bölümünün altına ekleyin. Düzey eklemeyin Rules .

Kural bölümleri

Kaynak kapsamına ve kuralın bir dinleyiciyi hedefleyip hedeflemediğine bağlı olarak bir kural bölümü seçin:

Bölüm	Eşleşen olay dinleyicileri	Eşleşen etkinlik kaynakları
`EnabledTracing`	Tüm kayıtlı dinleyiciler.	Genel ve yerel kaynaklar.
`EnabledGlobalTracing`	Tüm kayıtlı dinleyiciler.	Yalnızca global kaynaklar.
`EnabledLocalTracing`	Tüm kayıtlı dinleyiciler.	Yalnızca yerel kaynaklar.
`{Listener}:EnabledTracing`	Adlandırılmış dinleyici nesnesi.	Global ve yerel kaynaklar.
`{Listener}:EnabledGlobalTracing`	Adlandırılmış listener.	Yalnızca global kaynaklar.
`{Listener}:EnabledLocalTracing`	Adlandırılmış listener.	Yalnızca yerel kaynaklar.

Dinleyici adları, AddListener öğesine geçirilen adlarla eşleşir. Bölüm adları ve dinleyici adları büyük/küçük harfe duyarlı değildir.

Kural düzeyleri

Herhangi bir kural bölümünde aşağıdaki anahtar formlardan birini kullanın:

Ana form	Kural düzeyi	Eşleştir
`Default`	Default.	Her kaynak ve hedef.
`{SourceName}`	Etkinlik kaynağı.	Kaynakları eşleştirmedeki her işlem.
`{SourceName}:Default`	Etkinlik kaynağı.	Eşleşen kaynaklardaki tüm işlemler. Bu form, bir kaynağın işlem kuralları da içermesine olanak tanır.
`{SourceName}:{OperationName}`	İşlem.	Eşleşen kaynaklardaki adlandırılmış işlem

Eşleşmeyi etkinleştirmek için her yaprak değerini true olarak veya devre dışı bırakmak için false olarak ayarlayın. Örneğin, önceki yapılandırma:

İzlemeyi varsayılan olarak devre dışı bırakır.
Adı Contoso ile başlayan kaynakları etkinleştirir.
Contoso.Orders öğesini etkinleştirir, ancak HealthCheck işlemini devre dışı bırakır.
Contoso. ile başlayan ve .Storage ile biten bir kaynak deseni etkinleştirir.
Yalnızca genel kaynaklara, yerel kaynaklara veya Console adlı dinleyiciye uygulanan kurallar ekler.

Boolean yaprağı olarak Default kullanın. Default İşlem alt öğeleri içeriyorsa, yapılandırma Default öğesini değişmez bir etkinlik-kaynak adı olarak ele alır.

İzlemeyi kodla yapılandırma

AddTracing öğesine geçirilen ITracingBuilder üzerinde DisableTracing ve EnableTracing çağrısı yapın.

C#
Visual Basic

tracing.EnableTracing(sourceName: "Contoso");
tracing.DisableTracing(
    sourceName: "Contoso.Orders",
    operationName: "HealthCheck");

tracing.EnableTracing(sourceName:="Contoso")
tracing.DisableTracing(
    sourceName:="Contoso.Orders",
    operationName:="HealthCheck")

Bu düzeydeki tüm değerleri eşleştirmek için operationName, listenerName veya sourceName öğelerini atlayın. Varsayılan olarak, programatik bir kural hem genel hem de yerel kaynaklar için geçerlidir. Kuralı daraltmak için scopes, Local veya her ikisini de Global bağımsız değişkeni aracılığıyla geçirin.

Yapılandırma kuralları ve programatik kurallar tek bir sıralı kural kümesi oluşturur. Eşit derecede belirli kurallar çakışırsa, en son eklenen kural geçerli olur. Bu nedenle, geri çağırmadaki AddTracing çağrılarının sırası, EnableTracing, DisableTracing ve AddConfiguration eşit derecede belirli kurallar eklediğinde önemlidir.

Etkinlik kaynağı adlarını eşleştirin

Kaynak adları, işlem adları ve dinleyici adları büyük/küçük harfe duyarsız ordinal karşılaştırma kullanır. Kaynak adı kuralları şu eşleştirme formlarını destekler:

Boş bir kaynak adı her kaynakla eşleşir.
Joker karakter içermeyen bir kaynak adı önekine göre eşleşir. Örneğin, ContosoContoso.Orders ve ContosoPayments ile eşleşir; eşleyici ön ekin ardından ayırıcı gerektirmez.
Bir * joker karakteri içeren kaynak adı bir ön eki ve son eki eşleştirir. Örneğin, Contoso.*.Storage, Contoso.Orders.Storage ile eşleşir, ancak Contoso.Orders.Api ile eşleşmez.
* kaynak adı her kaynağı eşleştirir.

İşlem adları tam olarak eşleşmektedir. Onlar önek veya joker karakter eşleştirme kullanmaz.

Kural önceliğini uygula

Her dinleyici, kaynak, işlem ve kapsam bileşimi için izleme altyapısı bir eşleşen kural seçer. Eşleşen kuralları şu sırayla karşılaştırır:

Dinleyiciye özgü bir kural, tüm dinleyiciler için bir kuraldan önceliklidir.
Kaynak kuralı varsayılan kuraldan önceliklidir. İki kaynak ifade eşleşirse, uzun ifade öncelikli olur. Karşılaştırmada, * joker karakterini içeren ifade uzunluğu kullanılır.
İşlem kuralı, kaynak düzeyi kuralından önce gelir.
Yalnızca genel veya yalnızca yerel kural, her iki kapsamı da kapsayan bir kuraldan önceliklidir.
Önceki tüm faktörler eşit olduğunda son kural önceliklidir.

Karşılaştırma ilk farkta durur. Örneğin, dinleyiciye özgü varsayılan kural, önce dinleyicinin özgüllüğü değerlendirildiğinden, tüm dinleyiciler için geçerli olan kaynağa özgü bir kuraldan önceliklidir.

İşlem kuralları kaynak abonelikleri de denetler. Varsayılan olarak devre dışı olan bir kaynağa, bir işlem kuralı o kaynaktaki en az bir işlemi etkinleştirdiğinde dinleyici abone olur. Ardından dinleyici None döndürür ve devre dışı bırakılmış işlemler için geri çağırmaları atlar.

Genel veya yerel etkinlik kaynaklarını seçin

İzleme altyapısı iki etkinlik kaynağı kapsamını ayırt eder:

global kaynak, oluşturucu aracılığıyla oluşturulan bir ActivitySource kaynaktır. EnabledGlobalTracing kuralları bu kaynaklara uygulanır.
Yerel kaynak, bağımlılık enjeksiyonundan çözümlenen ActivitySource tarafından oluşturulan bir ActivitySourceFactory'dir. EnabledLocalTracing kuralları, söz konusu fabrika tarafından oluşturulan kaynaklara uygulanır.

Kaynağı ve izleme dinleyicilerini bağımlılık ekleme kapsayıcısının yönetmesini istediğinizde Create kullanın. Bir fabrikanın dinleyicileri farklı bir fabrika tarafından oluşturulan yerel kaynakları yoksayar. EnabledTracing içindeki kurallar her iki kaynak türü için de geçerlidir.

Bu kapsamlar yalnızca AddTracing tarafından kaydedilen dinleyicileri kısıtlar. Bağımsız ActivityListener, ActivitySourceFactory tarafından oluşturulan bir etkinlik kaynağı için bile kendi ShouldListenTo ve örnekleme geri çağrılarını kullanır.

İzleme yapılandırmasını yeniden yükle

AddConfiguration sağlanan yapılandırmadan değişiklik belirtecine abone olur. Yapılandırma sağlayıcısı yeniden yüklemeyi desteklediğinde ve değişiklik bildirdiğinde izleme altyapısı:

Kural kümesini yeniden oluşturur.
Kayıtlı dinleyicilerin kaynak aboneliklerini yeniler.
Güncelleştirilmiş kuralları sonraki etkinliklere uygular.

Uygulama, yeniden yüklemenin ardından aynı ActivitySource örneklerini kullanmaya devam edebilir. Sonraki etkinlikler güncelleştirilmiş kuralları kullanır.

Değişiklikleri otomatik olarak bildirmeyen değiştirilebilir bir sağlayıcı için yapılandırmayı güncelleştirin ve Reload çağırın. Tam örnek, bellek içi yapılandırma sağlayıcısıyla bu yaklaşımı kullanır.

Geçersiz yapılandırmayı işle

İzleme yapılandırması, değerleri TryParse ile ayrıştırır. true ve false değerlerini büyük/küçük harf duyarlılığı olmadan kabul eder ve çevresindeki boşluklara izin verir. 0, yes, on veya 1 kabul etmez.

Yapılandırma yükleyicisi, geçerli bir Boole olmayan yaprak değerini sessizce yoksayar. Ayrıca desteklenen şemayla eşleşmeyen bilinmeyen veya hatalı biçimlendirilmiş bölümleri de yoksayar. Bu durumlar istisna oluşturmadığından anahtar adlarını dikkatle denetleyin.

Kaynak ifade en fazla bir * joker karakter içerebilir. Birden fazla joker karakter içeren bir kural, uygulama başlatılırken veya yapılandırma yeniden yüklendikten sonra kural somutlaştırıldığında bir ArgumentException oluşturur. Programatik kurallar için de None bir ArgumentOutOfRangeException neden olur.

Örneği çalıştırma

Aşağıdaki .NET 11 konsol uygulaması bir etkin işlem ve bir devre dışı işlem oluşturur. Ardından devre dışı bırakılan işlemin kuralını güncelleştirir, Reload çağırır ve işlemi aynı yerel ActivitySource üzerinden yeniden başlatır.

using System.Diagnostics;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Diagnostics.Tracing;

IConfigurationRoot configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>
    {
        ["Tracing:EnabledTracing:Default"] = "false",
        ["Tracing:EnabledTracing:Contoso.Orders:Default"] = "true",
        ["Tracing:EnabledTracing:Contoso.Orders:DisabledOperation"] = "false",
    })
    .Build();

ServiceCollection services = new();
services.AddTracing(tracing =>
{
    tracing.AddListener("Console", listener =>
    {
        listener.Sample = static (ref ActivityCreationOptions<ActivityContext> _) =>
            ActivitySamplingResult.AllData;
        listener.SampleUsingParentId = static (ref ActivityCreationOptions<string> _) =>
            ActivitySamplingResult.AllData;
        listener.ActivityStarted = activity =>
            Console.WriteLine($"Listener started: {activity.OperationName}");
    });
    tracing.AddConfiguration(configuration.GetSection("Tracing"));
});

using ServiceProvider serviceProvider = services.BuildServiceProvider();
ActivitySourceFactory factory =
    serviceProvider.GetRequiredService<ActivitySourceFactory>();
using ActivitySource source = factory.Create("Contoso.Orders");

Console.WriteLine("Before reload:");
WriteResult(source, "EnabledOperation");
WriteResult(source, "DisabledOperation");

configuration["Tracing:EnabledTracing:Contoso.Orders:DisabledOperation"] = "true";
configuration.Reload();

Console.WriteLine("After reload:");
WriteResult(source, "DisabledOperation");

static void WriteResult(ActivitySource source, string operationName)
{
    using Activity? activity = source.StartActivity(operationName);
    string state = activity is null ? "disabled" : "enabled";
    Console.WriteLine($"{operationName}: {state}");
}

Imports System.Diagnostics
Imports Microsoft.Extensions.Configuration
Imports Microsoft.Extensions.DependencyInjection
Imports Microsoft.Extensions.Diagnostics.Tracing

Module Program
    Sub Main()
        Dim initialData As New Dictionary(Of String, String) From {
            {"Tracing:EnabledTracing:Default", "false"},
            {"Tracing:EnabledTracing:Contoso.Orders:Default", "true"},
            {"Tracing:EnabledTracing:Contoso.Orders:DisabledOperation", "false"}
        }

        Dim configuration As IConfigurationRoot =
            New ConfigurationBuilder().AddInMemoryCollection(initialData).Build()

        Dim services As New ServiceCollection()
        services.AddTracing(
            Sub(tracing)
                tracing.AddListener(
                    "Console",
                    Sub(listener)
                        listener.Sample = AddressOf SampleActivity
                        listener.SampleUsingParentId = AddressOf SampleActivityUsingParentId
                        listener.ActivityStarted =
                            Sub(activity) Console.WriteLine(
                                $"Listener started: {activity.OperationName}")
                    End Sub)
                tracing.AddConfiguration(configuration.GetSection("Tracing"))
            End Sub)

        Using serviceProvider As ServiceProvider = services.BuildServiceProvider()
            Dim factory As ActivitySourceFactory =
                serviceProvider.GetRequiredService(Of ActivitySourceFactory)()

            Using source As ActivitySource = factory.Create("Contoso.Orders")
                Console.WriteLine("Before reload:")
                WriteResult(source, "EnabledOperation")
                WriteResult(source, "DisabledOperation")

                configuration(
                    "Tracing:EnabledTracing:Contoso.Orders:DisabledOperation") = "true"
                configuration.Reload()

                Console.WriteLine("After reload:")
                WriteResult(source, "DisabledOperation")
            End Using
        End Using
    End Sub

    Private Function SampleActivity(
        ByRef options As ActivityCreationOptions(Of ActivityContext)
    ) As ActivitySamplingResult
        Return ActivitySamplingResult.AllData
    End Function

    Private Function SampleActivityUsingParentId(
        ByRef options As ActivityCreationOptions(Of String)
    ) As ActivitySamplingResult
        Return ActivitySamplingResult.AllData
    End Function

    Private Sub WriteResult(source As ActivitySource, operationName As String)
        Using activity As Activity = source.StartActivity(operationName)
            Dim state As String = If(activity Is Nothing, "disabled", "enabled")
            Console.WriteLine($"{operationName}: {state}")
        End Using
    End Sub
End Module

C# ve Visual Basic örnekleri aynı sonucu üretir:

Before reload:
Listener started: EnabledOperation
EnabledOperation: enabled
DisabledOperation: disabled
After reload:
Listener started: DisabledOperation
DisabledOperation: enabled

Ayrıca bkz.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-10-22