语言

在 .NET 中配置分布式跟踪

在 .NET 11 及更高版本中,Microsoft.Extensions.Diagnostics.TracingAPI 允许注册ActivityListener实例并使用规则来选择每个侦听器接收的ActivitySource实例和Activity实例。 在代码中定义规则或从 IConfiguration中加载规则。

Important

跟踪规则仅影响通过此跟踪基础结构注册的侦听器。 它们不会影响不相关的 ActivityListener 实例,包括遥测导出程序创建和管理的侦听器。 单独配置这些监听器或导出器。

寄存器跟踪

这些 API 可在 Microsoft.Extensions.Diagnostics 包中使用。 引用 Microsoft.AspNetCore.App 共享框架的应用已包含程序集。

在一个 IServiceCollection 上拨打 AddTracing。 在回调中:

  • 调用 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
        }
      }
    }
  }
}

直接在 EnabledTracing、EnabledGlobalTracing 或 EnabledLocalTracing 节下添加规则。 不要添加 Rules 级别。

规则部分

根据源范围以及规则是否面向一个侦听器选择规则部分:

部分 匹配监听器 匹配活动来源
EnabledTracing 所有已注册的侦听器。 全局和本地源。
EnabledGlobalTracing 所有已注册的监听器。 仅限全局来源。
EnabledLocalTracing 所有已注册的监听器。 仅限本地源。
{Listener}:EnabledTracing 命名的侦听器。 全局和本地源。
{Listener}:EnabledGlobalTracing 命名的侦听器。 仅限全局来源。
{Listener}:EnabledLocalTracing 命名的侦听器。 仅限本地源。

侦听器名称与传递给 AddListener 的名称一致。 节名称和侦听器名称不区分大小写。

规则级别

在任何规则节下,使用以下键形式之一:

键形式 规则级别 匹配
Default 违约。 每个源和操作。
{SourceName} 活动源。 来自匹配源的每个操作。
{SourceName}:Default 活动源。 来自匹配源的每个操作。 此窗体允许源还包含操作规则。
{SourceName}:{OperationName} 操作。 来自匹配源的命名操作。

将每个叶值设置为 true 以启用匹配,或设置为 false 以禁用匹配。 例如,上述配置:

  • 默认禁用跟踪。
  • 启用名称以Contoso开头的源。
  • 启用 Contoso.Orders,但禁用其 HealthCheck 操作。
  • 启用以 .Storage 开头并以 Contoso. 结尾的源模式。
  • 添加仅适用于全局源、本地源或名为 Console侦听器的规则。

将 Default 用作布尔叶节点。 如果 Default 包含操作子级,则配置将 Default 视为字面活动源名称。

使用代码配置跟踪

对传递给 AddTracing 的 ITracingBuilder 调用 EnableTracing 和 DisableTracing。

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

省略 sourceName、operationName 或 listenerName,以匹配该级别的所有值。 默认情况下,编程规则同时适用于全局源和本地源。 通过 scopes 参数传递 Global、Local 或两者,以缩小规则范围。

配置规则和程序化规则构成一个有序规则集。 如果同样特定的规则发生冲突,最后添加的规则胜出。 因此,当 AddConfiguration、EnableTracing 和 DisableTracing 添加同样具体的规则时,回调中的 AddTracing 的调用顺序很重要。

匹配活动源名称

源名称、操作名称和侦听器名称使用不区分大小写的序号比较规则。 源名称规则支持以下匹配形式:

  • 空源名称匹配所有源。
  • 没有通配符的源名称按前缀匹配。 例如, Contoso 匹配 Contoso.Orders 项和 ContosoPayments;匹配程序不需要前缀后的分隔符。
  • 带有一个 * 通配符的源名称匹配前缀和后缀。 例如,Contoso.*.Storage 与 Contoso.Orders.Api 匹配,但与 Contoso.Orders.Storage 不匹配。
  • 源名称为 * 时,将匹配所有源。

操作名称完全匹配。 它们不使用前缀或通配符匹配。

应用规则优先级

对于每个侦听器、源、操作和范围组合,跟踪基础结构选择一个匹配规则。 它按以下顺序比较匹配规则:

  • 特定于侦听器的规则优先于所有侦听器的规则。
  • 源规则优先于默认规则。 如果两个源表达式匹配,则较长的表达式优先。 比较使用表达式长度,包括 * 通配符。
  • 操作规则优先于源级规则。
  • 仅全局规则或仅本地规则优先于涵盖这两个范围的规则。
  • 当上述所有因素相等时,最后一个规则优先。

比较在第一个差异处停止。 例如,特定于侦听器的默认规则优先于适用于所有侦听器的特定于源的规则,因为首先评估侦听器的特定性。

操作规则还控制源订阅。 当操作规则启用来自该源的至少一个操作时,侦听器会订阅默认禁用的源。 然后,侦听器返回 None 并跳过已禁用操作的回调。

选择全局或本地活动源

跟踪基础结构区分两种 ActivitySource 作用域:

  • 全局源是通过其构造函数创建的 ActivitySource。 EnabledGlobalTracing 规则适用于这些源。
  • 本地源是由从依赖项注入解析的 ActivitySourceFactory 创建的 ActivitySource。 EnabledLocalTracing 规则适用于该工厂创建的源。

当希望依赖项注入容器管理源及其跟踪侦听器时使用 Create 。 工厂的监听器会忽略由其他工厂创建的本地源。 EnabledTracing 中的规则适用于两种源类型。

这些范围仅限制 AddTracing 注册的侦听器。 独立的 ActivityListener 使用自己的 ShouldListenTo 和采样回调,即使对于由 ActivitySourceFactory 创建的活动源也是如此。

重新加载跟踪配置

AddConfiguration 订阅所提供配置的更改令牌。 当配置提供程序支持重新加载并报告更改时,跟踪基础结构:

  • 重新生成规则集。
  • 刷新每个已注册侦听器的源订阅。
  • 将更新的规则应用于后续活动。

重新加载后,应用可以继续使用相同的 ActivitySource 实例。 后续活动使用更新的规则。

对于不自动报告更改的可变提供程序,请更新配置和调用 Reload。 完整示例将此方法与内存中配置提供程序配合使用。

处理无效配置

跟踪配置使用 TryParse 解析值。 它接受 true 和 false,不区分大小写,并允许前后有空白字符。 它不接受1、0、yes或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

另请参阅