Configurar rastreamento distribuído em .NET

No .NET 11 e posteriores, as Microsoft.Extensions.Diagnostics.Tracing APIs permitem-lhe registar instâncias de ActivityListener e usar regras para selecionar as instâncias de ActivitySource e Activity que cada listener recebe. Defina regras no código ou carregue-as a partir de IConfiguration.

Importante

As regras de rastreio afetam apenas os ouvintes registados através desta infraestrutura de rastreio. Não afetam instâncias não relacionadas ActivityListener , incluindo ouvintes que os exportadores de telemetria criam e gerem. Configure esses listeners ou exportadores em separado.

Rastreio de registadores

As APIs estão disponíveis no Microsoft.Extensions.Diagnostics pacote. As aplicações que referenciam o Microsoft.AspNetCore.App framework partilhado já incluem a assembly.

Ligue para AddTracing num IServiceCollection. No callback:

• Ligue AddListener para registar cada listener. O nome do listener identifica o listener nas regras de configuração.
• Configure os delegados de amostragem e notificação do ouvinte através de ActivityListenerBuilder. A infraestrutura de rastreio detém ShouldListenTo, as subscrições da origem e o tempo de vida do ouvinte.
• Invoque AddConfiguration com a secção de configuração que contém as regras. Para uma secção chamada Tracing, passe configuration.GetSection("Tracing").

A amostra completa mostra as três calls. Um anfitrião .NET ativa subscrições de rastreamento quando o anfitrião inicia. Se usar injeção de dependência sem um host, resolva o ActivitySourceFactory registado para construir os ouvintes e ativar as suas subscrições. A amostra completa resolve diretamente a factory.

Configurar o rastreio

Defina regras de rastreio através da configuração ou em código. Se nenhuma regra corresponder a um ouvinte, fonte, operação e âmbito, o rastreio permanece desativado para essa combinação.

Configurar o rastreio sem código

Para aplicações que usam configuração, adicione uma secção Tracing ao appsettings.json ou a outro fornecedor de configuração. Depois passe essa secção para AddConfiguration:

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

O exemplo seguinte mostra as secções e níveis de regras suportados:

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

Adicione regras diretamente sob uma secção EnabledTracing, EnabledGlobalTracing ou EnabledLocalTracing. Não adicione um Rules nível.

Secções das regras

Escolha uma secção de regras com base no âmbito de origem e se a regra tem como alvo um ouvinte:

Secção	Ouvintes correspondentes	Correspondência entre origens de atividade
EnabledTracing	Todos os ouvintes registados.	Fontes globais e locais.
EnabledGlobalTracing	Todos os ouvintes registados.	Apenas fontes globais.
EnabledLocalTracing	Todos os ouvintes registados.	Apenas fontes locais.
{Listener}:EnabledTracing	O listener nomeado.	Fontes globais e locais.
{Listener}:EnabledGlobalTracing	O listener com nome.	Apenas fontes globais.
{Listener}:EnabledLocalTracing	O observador com nome.	Apenas fontes locais.

Os nomes dos ouvintes correspondem aos nomes passados para AddListener. Os nomes das secções e dos listeners não são sensíveis a maiúsculas e minúsculas.

Níveis de regra

Em qualquer secção de regras, use uma das seguintes formas-chave:

Formulário de chave	Nível da regra	Match
Default	Predefinido.	Todas as origens e operação.
{SourceName}	Fonte da atividade.	Cada operação de correspondência de fontes.
{SourceName}:Default	Fonte da atividade.	Cada operação a partir de fontes de correspondência. Este formulário permite que uma fonte também contenha regras de operação.
{SourceName}:{OperationName}	Operação.	A operação nomeada de origens correspondentes.

Defina cada valor de folha como true para permitir a correspondência ou false para desativá-la. Por exemplo, a configuração anterior:

• Desativa o rastreio por defeito.
• Permite origens cujos nomes começam por Contoso.
• Ativa Contoso.Orders, mas desativa a sua operação HealthCheck.
• Permite um padrão fonte que começa com Contoso. e termina em .Storage.
• Adiciona regras que se aplicam apenas a fontes globais, fontes locais ou ao ouvinte chamado Console.

Usar Default como nó folha booleano. Se Default contém filhos de operação, a configuração trata Default como um nome literal da origem da atividade.

Configurar rastreamento com código

Chamar EnableTracing e DisableTracing no ITracingBuilder passado para AddTracing.

C#

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

Visual Basic

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

Omita sourceName, operationName ou listenerName para incluir todos os valores desse nível. Por defeito, uma regra programática aplica-se tanto a fontes globais como locais. Passe Global, Local ou ambos no argumento scopes para restringir a regra.

As regras de configuração e as regras programáticas formam um conjunto de regras ordenado. Se regras igualmente específicas entrarem em conflito, a regra adicionada por último vence. A ordem das chamadas no AddTracing callback importa, portanto, quando AddConfiguration, EnableTracing, e DisableTracing adicionam regras igualmente específicas.

Fazer corresponder os nomes da origem da atividade

Nomes de origem, nomes de operações e nomes de listeners utilizam comparação ordinal insensível a maiúsculas e minúsculas. As regras de nome de origem aceitam estas formas de correspondência:

• Um nome de fonte vazio corresponde a qualquer fonte.
• Um nome de origem sem um coringa corresponde por prefixo. Por exemplo, Contoso corresponde a Contoso.Orders e a ContosoPayments; o emparelhador não requer um separador após o prefixo.
• Um nome de origem com um * wildcard corresponde a um prefixo e sufixo. Por exemplo, Contoso.*.Storage corresponde a Contoso.Orders.Storage, mas não a Contoso.Orders.Api.
• Um nome de origem * corresponde a todas as origens.

Os nomes das operações correspondem exatamente. Eles não usam prefixos nem correspondência com wildcard.

Aplicar a ordem de precedência das regras

Para cada combinação de ouvinte, fonte, operação e âmbito, a infraestrutura de rastreamento escolhe uma regra correspondente. Compara as regras de correspondência por esta ordem:

• Uma regra específica para o ouvinte tem prioridade sobre uma regra para todos os ouvintes.
• Uma regra de origem tem precedência sobre uma regra padrão. Se duas expressões de origem coincidirem, a expressão mais longa tem prioridade. A comparação utiliza o comprimento da expressão, incluindo um * coringa.
• Uma regra de operação tem precedência sobre uma regra ao nível da origem.
• Uma regra apenas global ou apenas local tem precedência sobre uma regra que abrange ambos os âmbitos.
• A última regra tem precedência quando todos os fatores anteriores são iguais.

A comparação termina na primeira diferença. Por exemplo, uma regra predefinida específica do listener tem precedência sobre uma regra específica da origem que se aplica a todos os listeners, porque a especificidade do listener é avaliada primeiro.

As regras de operação também controlam as subscrições de origem. Um ouvinte subscreve uma fonte que está desativada por defeito quando uma regra de operação permite pelo menos uma operação dessa fonte. O listener devolve então None e omite as chamadas de retorno para operações desativadas.

Escolha fontes de atividade globais ou locais

A infraestrutura de rastreio distingue dois âmbitos de fonte de atividade:

• Uma fonte global é uma ActivitySource criada através do seu construtor. EnabledGlobalTracing As regras aplicam-se a estas origens.
• Uma fonte local é uma ActivitySource criada pelo ActivitySourceFactory resolvido a partir da injeção de dependências. EnabledLocalTracing As regras aplicam-se às origens criadas por essa fábrica.

Usa Create quando quiseres que o contentor de injeção de dependências gere a fonte e as suas escutas de rastreio. Os listeners de uma fábrica ignoram origens locais criadas por uma fábrica diferente. As regras em EnabledTracing aplicam-se a ambos os tipos de origem.

Estes escopos restringem apenas os ouvintes que AddTracing regista. Um ActivityListener independente usa os seus próprios callbacks ShouldListenTo e de amostragem, mesmo para uma fonte de atividade criada por ActivitySourceFactory.

Recarregar configuração de rastreio

AddConfiguration subscreve ao token de alteração da configuração fornecida. Quando um provedor de configuração suporta o recarregamento e reporta uma alteração, a infraestrutura de rastreio:

• Reconstrói o conjunto de regras.
• Atualiza as subscrições de origem de cada listener registado.
• Aplica as regras atualizadas a atividades subsequentes.

A aplicação pode continuar a usar as mesmas ActivitySource instâncias após uma recarga. As atividades subsequentes utilizam as regras atualizadas.

Para um fornecedor mutável que não reporta alterações automaticamente, atualize a configuração e chame Reload. A amostra completa utiliza esta abordagem com o provedor de configuração na memória.

Lidar com configuração inválida

A configuração de rastreio analisa valores com TryParse. Aceita true e false sem distinção entre maiúsculas e minúsculas e permite espaços em branco envolventes. Não aceita 1, 0, yes, ou on.

O carregador de configuração ignora silenciosamente um valor de folha que não é um Booleano válido. Também ignora secções desconhecidas ou mal formadas que não correspondem ao esquema suportado. Verifique cuidadosamente os nomes-chave porque estes casos não produzem exceção.

Uma expressão de origem pode conter, no máximo, um * coringa. Uma regra com mais do que um coringa lança um ArgumentException quando a regra é materializada, seja durante o arranque da aplicação ou após o recarregamento da configuração. Para regras programáticas, None também causa ArgumentOutOfRangeException.

Executar o exemplo

A seguinte aplicação de consola .NET 11 cria uma operação ativada e uma desativada. Depois, atualiza a regra da operação desativada, chama Reload, e inicia a operação novamente através do mesmo local 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

Os exemplos de C# e Visual Basic produzem o mesmo resultado:

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

Ver também

• Visão geral do rastreio distribuído
• Configuração em .NET
• Configuração do rastreio de atividade em O que há de novo no .NET 11