Настройка распределенной трассировки в .NET

В .NET 11 и более поздних версиях API Microsoft.Extensions.Diagnostics.Tracing позволяют регистрировать экземпляры ActivityListener и использовать правила для выбора экземпляров ActivitySource и Activity, которые получает каждый слушатель. Определите правила в коде или загрузите их из IConfiguration.

Important

Правила трассировки влияют только на слушатели, зарегистрированные в этой инфраструктуре трассировки. Они не влияют на несвязанные ActivityListener экземпляры, включая прослушиватели, которые создаются и управляются экспортерами телеметрии. Настройте эти слушатели или экспортеры отдельно.

Трассировка регистра

API доступны в пакете Microsoft.Extensions.Diagnostics . Приложения, ссылающиеся на Microsoft.AspNetCore.App общую платформу, уже включают сборку.

Позвоните AddTracing на IServiceCollection. В колбэке:

Вызовите AddListener для регистрации каждого обработчика. Имя прослушивателя идентифицирует прослушиватель в правилах конфигурации.
Настройте через ActivityListenerBuilder делегаты выборки и уведомлений прослушивателя. Инфраструктура трассировки владеет ShouldListenTo, исходными подписками и временем существования прослушивателя.
Вызовите AddConfiguration с разделом конфигурации, содержащим правила. Для раздела с именем Tracing, передайте configuration.GetSection("Tracing").

Полный пример показывает все три вызова. Хост .NET активирует подписки трассировки при запуске хоста. Если вы используете внедрение зависимостей без хоста, получите зарегистрированный ActivitySourceFactory для создания прослушивателей и активации их подписок. Полный пример непосредственно получает фабрику.

Настроить трассировку

Задайте правила трассировки с помощью конфигурации или кода. Если ни одно правило не применяется к прослушивателю, источнику, операции и области, трассировка остается отключенной для этой комбинации.

Настройка трассировки без кода

Для приложений, использующих конфигурацию, добавьте раздел Tracing в appsettings.json или в другой поставщик конфигурации. Затем передайте этот раздел AddConfiguration:

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

В следующем примере показаны поддерживаемые разделы правил и уровни правил:

{
  "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
        }
      }
    }
  }
}

Добавьте правила непосредственно под разделом EnabledLocalTracing, EnabledTracing или EnabledGlobalTracing. Не добавляйте уровень Rules.

Разделы правил

Выберите раздел правила на основе области источника и того, нацелено ли правило на один обработчик:

Секция	Подходящие слушатели	Совпадающие источники активности
`EnabledTracing`	Все зарегистрированные слушатели.	Глобальные и локальные источники.
`EnabledGlobalTracing`	Все зарегистрированные обработчики.	Только глобальные источники.
`EnabledLocalTracing`	Все зарегистрированные слушатели.	Только локальные источники.
`{Listener}:EnabledTracing`	Именованный обработчик.	Глобальные и локальные источники.
`{Listener}:EnabledGlobalTracing`	Именованный обработчик.	Только глобальные источники.
`{Listener}:EnabledLocalTracing`	Именованный обработчик.	Только локальные источники.

Имена прослушивателей соответствуют именам, переданным в AddListener. Имена разделов и имена обработчиков не учитывают регистр.

Уровни правил

В любом разделе правила используйте одну из следующих ключевых форм:

Форма ввода ключа	Уровень правила	Матч
`Default`	Default.	Каждый источник и каждая операция.
`{SourceName}`	Источник действия.	Каждая операция по сопоставлению источников.
`{SourceName}:Default`	Источник действия.	Каждая операция из совпадающих источников. Эта форма также позволяет источнику содержать правила операций.
`{SourceName}:{OperationName}`	Операция.	Именованная операция из соответствующих источников.

Задайте для каждого значения листа значение true, чтобы включить совпадение, или false, чтобы отключить его. Например, предыдущая конфигурация:

По умолчанию отключает трассировку.
Включает источники, имена которых начинаются с Contoso.
Включает Contoso.Orders, но отключает связанную с ним операцию HealthCheck.
Включает исходный шаблон, который начинается с Contoso. и заканчивается .Storage.
Добавляет правила, которые применяются только к глобальным источникам, локальным источникам или прослушивателю с именем Console.

Используйте Default в качестве листового логического узла. Если Default содержит дочерние элементы операций, конфигурация рассматривает Default как буквальное имя источника действия.

Настройка трассировки с помощью кода

Вызовите EnableTracing и DisableTracing для AddTracing, переданного в ITracingBuilder.

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

Опустите sourceName, operationName или listenerName, чтобы сопоставить все значения на этом уровне. По умолчанию программное правило применяется как к глобальным, так и к локальным источникам. Передайте Global, Local или оба через аргумент scopes, чтобы сузить правило.

Правила конфигурации и программные правила формируют один упорядоченный набор правил. Если конфликтуют одинаково конкретные правила, побеждает правило, добавленное последним. Таким образом, порядок вызовов в функции обратного вызова AddTracing имеет значение, когда AddConfiguration, EnableTracing и DisableTracing добавляют одинаково специфичные правила.

Сопоставить имена источников активности

Имена источников, имена операций и имена прослушивателей используют порядковое сравнение без учета регистра. Правила исходного имени поддерживают следующие формы сопоставления:

Пустое имя источника соответствует каждому источнику.
Имя источника без подстановочного знака совпадает по префиксу. Например, Contoso совпадает с Contoso.Orders и ContosoPayments; сопоставитель не требует разделителя после префикса.
Имя источника с одним * подстановочным знаком совпадает с именем, имеющим префикс и суффикс. Например, Contoso.*.Storage совпадает с Contoso.Orders.Storage, но не с Contoso.Orders.Api.
Исходное имя * соответствует каждому источнику.

Имена операций совпадают точно. Они не используют префиксное сопоставление или сопоставление по шаблону.

Применить приоритет правила

Для каждой комбинации прослушивателя, источника, операции и области действия инфраструктура трассировки выбирает одно соответствующее правило. Он сравнивает соответствующие правила в этом порядке:

Правило, специфичное для прослушивателя, имеет приоритет над правилом для всех прослушивателей.
Исходное правило имеет приоритет над правилом по умолчанию. Если совпадают два исходных выражения, то более длинное выражение имеет приоритет. Сравнение использует длину выражения с подстановочным знаком *.
Правило операции имеет приоритет над правилом уровня источника.
Глобальное или локальное правило имеет приоритет над правилом, охватывающим обе области.
Последнее правило имеет приоритет при равенстве всех предыдущих факторов.

Сравнение прекращается при первом различии. Например, правило по умолчанию для конкретного listener имеет приоритет над правилом для конкретного источника, которое применяется ко всем listeners, так как специфичность listener оценивается сначала.

Правила работы также управляют подписками на источники. Слушатель подписывается на источник, отключенный по умолчанию, когда правило операции включает по крайней мере одну операцию из этого источника. Затем обработчик возвращает None и пропускает обратные вызовы для отключенных операций.

Выберите глобальные или локальные источники активности

Инфраструктура трассировки различает две области действия источника активности:

Глобальный источник — это ActivitySource объект, созданный с помощью конструктора. EnabledGlobalTracing правила применяются к этим источникам.
Локальный источник — это ActivitySource объект, созданный ActivitySourceFactory, разрешенным через внедрение зависимостей. EnabledLocalTracing правила применяются к источникам, созданным той фабрикой.

Используйте Create, если требуется, чтобы контейнер внедрения зависимостей управлял источником и его прослушивателями трассировки. Обработчики фабрики игнорируют локальные источники, созданные другой фабрикой. Правила применяются EnabledTracing к обоим типам источников.

Эти области ограничивают только обработчики, которые регистрирует AddTracing. ActivityListener Независимый использует собственные ShouldListenTo и обратные вызовы выборки, даже для источника действия, созданного ActivitySourceFactory.

Перезагрузить конфигурацию трассировки

AddConfiguration подписывается на маркер изменений указанной конфигурации. Если поставщик конфигурации поддерживает перезагрузку и сообщает об изменении, инфраструктура трассировки:

Перестраивает набор правил.
Обновляет исходные подписки каждого зарегистрированного слушателя.
Применяет обновленные правила к последующим действиям.

Приложение может продолжать использовать те же ActivitySource экземпляры после перезагрузки. Последующие действия выполняются по обновленным правилам.

Для изменяемого поставщика, который не сообщает об изменениях автоматически, обновите конфигурацию и вызовите Reload. Полный пример использует этот подход с поставщиком конфигурации в памяти.

Обработайте недопустимую конфигурацию

Конфигурация трассировки разбирает значения с помощью TryParse. Он принимает true и false без учета регистра и разрешает окружающие пробелы. Он не принимает 1, 0yesили on.

Загрузчик конфигурации молча игнорирует конечное значение, которое не является допустимым логическим значением. Он также игнорирует неизвестные или неправильно сформированные разделы, которые не соответствуют поддерживаемой схеме. Тщательно проверьте имена ключей, так как эти случаи не создают исключения.

Исходное выражение может содержать не более одного * подстановочного знака. Правило с несколькими подстановочными знаками вызывает ArgumentException при материализации правила во время запуска приложения или после перезагрузки конфигурации. Для программных правил None также вызывает ArgumentOutOfRangeException.

Запустите пример

Следующее консольное приложение .NET 11 создает одну включенную операцию и одну отключенную операцию. Затем он обновляет правило отключенной операции, вызывает Reload и снова запускает операцию через тот же локальный ActivitySource.

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# и Visual Basic приводят к тому же результату:

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

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-10-22