Instrument .NET applications and report traces using Zipkin - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

Escolha um método de instrumentação

Selecione o método adequado ao framework do seu aplicativo.

Método	Mais indicado para	Pacotes NuGet necessários
ASP.NET Core	Aplicativos web multiplataforma desenvolvidos com ASP.NET Core	`zipkin4net.middleware.aspnetcore`, `zipkin4net`
OWIN	Aplicativos web do .NET Framework que usam middleware OWIN	`zipkin4net.middleware.aspnetcore`, `zipkin4net`
Manual	Jobs em segundo plano, consumidores de mensagens ou protocolos personalizados que exigem controle refinado de spans	`zipkin4net`

Pré-requisitos

Antes de começar, verifique se você tem:

Uma conta Alibaba Cloud com o ARMS ativado
Um ambiente de desenvolvimento .NET
O endpoint do Zipkin da sua instância do ARMS Tracing Analysis (consulte Obter um endpoint do Zipkin)

Obter um endpoint do Zipkin

Faça login no console do Tracing Analysis.
No painel de navegação à esquerda, clique em Cluster Configurations. Em seguida, clique na aba Access point information.
Na barra de navegação superior, selecione uma região. Na seção Cluster Information, ative Show Token.
Na seção Client, clique em Jaeger ou Zipkin.
Na coluna Related Information, copie a URL do endpoint.

Endpoint of Jaeger or Zipkin

Nota

Se o aplicativo for executado em um ambiente de produção da Alibaba Cloud, use um ponto de acesso VPC. Caso contrário, use um endpoint público. Prefira o endpoint v2, a menos que haja um motivo específico para usar a versão v1.

Instrumentar com ASP.NET Core

Nota

Baixe o projeto de demonstração completo e siga as instruções no arquivo README.md.

Etapa 1: Instale pacotes NuGet

dotnet add package zipkin4net.middleware.aspnetcore
dotnet add package zipkin4net

Pacote	Finalidade
`zipkin4net`	Biblioteca principal de rastreamento. Crie spans, gerencia amostragem e relata dados de rastreamento para um backend compatível com Zipkin.
`zipkin4net.middleware.aspnetcore`	Middleware para ASP.NET Core. Gera automaticamente um span de servidor para cada requisição HTTP recebida.

Etapa 2: Registrar e iniciar o tracer

Adicione o código abaixo à lógica de inicialização do aplicativo para configure o zipkin4net e conectá-lo ao endpoint do ARMS Tracing Analysis.

lifetime.ApplicationStarted.Register(() => {
    TraceManager.SamplingRate = 1.0f;
    var logger = new TracingLogger(loggerFactory, "zipkin4net");

    // Replace with your Zipkin endpoint from the Tracing Analysis console.
    // Do not append /api/v2/spans to the URL.
    var httpSender = new HttpZipkinSender("<your-zipkin-endpoint>", "application/json");

    var tracer = new ZipkinTracer(httpSender, new JSONSpanSerializer());
    TraceManager.RegisterTracer(tracer);
    TraceManager.Start(logger);
});
lifetime.ApplicationStopped.Register(() => TraceManager.Stop());
app.UseTracing(applicationName);

Substitua o placeholder abaixo pelo valor real:

Placeholder	Descrição	Exemplo
`<your-zipkin-endpoint>`	Endpoint do Zipkin obtido no console do Tracing Analysis	`http://tracing-analysis-dc-hz.aliyuncs.com/adapt_your_token`

Etapa 3: Rastrear requisições HTTP de saída

Inclua o TracingHandler no pipeline do HttpClient para rastrear chamadas HTTP externas automaticamente e correlacioná-las ao span pai.

public override void ConfigureServices(IServiceCollection services)
{
    services.AddHttpClient("Tracer").AddHttpMessageHandler(provider =>
        TracingHandler.WithoutInnerHandler(provider.GetService<IConfiguration>()["applicationName"]));
}

Instrumentar com OWIN

O Open Web Interface for .NET (OWIN) é uma especificação de middleware para aplicativos web baseados no .NET Framework.

Nota

Baixe o projeto de demonstração completo e siga as instruções no arquivo README.md.

Etapa 1: Instale pacotes NuGet

dotnet add package zipkin4net.middleware.aspnetcore
dotnet add package zipkin4net

Pacote	Finalidade
`zipkin4net`	Biblioteca principal de rastreamento.
`zipkin4net.middleware.aspnetcore`	Middleware para ASP.NET Core. Gera automaticamente um span de servidor para cada requisição HTTP recebida.

Etapa 2: Registrar e iniciar o tracer

// Configure tracing.
TraceManager.SamplingRate = 1.0f;
var logger = new ConsoleLogger();

// Replace with your Zipkin endpoint from the Tracing Analysis console.
// Do not append /api/v2/spans to the URL.
var httpSender = new HttpZipkinSender("<your-zipkin-endpoint>", "application/json");

var tracer = new ZipkinTracer(httpSender, new JSONSpanSerializer());
TraceManager.RegisterTracer(tracer);
TraceManager.Start(logger);

// Stop TraceManager when the application shuts down.
var properties = new AppProperties(appBuilder.Properties);
var token = properties.OnAppDisposing;

if (token != CancellationToken.None)
{
    token.Register(() =>
    {
        TraceManager.Stop();
    });
}

// Register OWIN middleware.
appBuilder.UseZipkinTracer(System.Configuration.ConfigurationManager.AppSettings["applicationName"]);

Etapa 3: Rastrear requisições HTTP de saída

Envolva o HttpClient com o TracingHandler para propagar o contexto de rastreamento entre serviços.

using (var httpClient = new HttpClient(new TracingHandler(applicationName)))
{
    var response = await httpClient.GetAsync(callServiceUrl);
    var content = await response.Content.ReadAsStringAsync();

    await context.Response.WriteAsync(content);
}

Instrumentar manualmente

Use a instrumentação manual para ter controle total sobre a criação de spans — ideal para rastrear jobs em segundo plano, consumidores de mensagens ou protocolos personalizados.

Nota

Baixe o projeto de demonstração completo e siga as instruções no arquivo README.md.

Etapa 1: Instale o pacote NuGet

Apenas a biblioteca principal de rastreamento é necessária para instrumentação manual.

dotnet add package zipkin4net

Etapa 2: Registrar e iniciar o tracer

TraceManager.SamplingRate = 1.0f;
var logger = new ConsoleLogger();

// Replace with your Zipkin endpoint from the Tracing Analysis console.
// Do not append /api/v2/spans to the URL.
var httpSender = new HttpZipkinSender("<your-zipkin-endpoint>", "application/json");

var tracer = new ZipkinTracer(httpSender, new JSONSpanSerializer());
TraceManager.RegisterTracer(tracer);
TraceManager.Start(logger);

Etapa 3: Crie e registrar spans

Crie um span raiz para cada requisição ou operação e registre os eventos de ciclo de vida correspondentes.

var trace = Trace.Create();

Trace.Current = trace;
trace.Record(Annotations.ClientSend());

trace.Record(Annotations.Rpc("client"));
trace.Record(Annotations.Tag("mytag", "spanFrist"));
trace.Record(Annotations.ServiceName("dotnetManual"));
// ... perform your operation here
testCall();

trace.Record(Annotations.ClientRecv());

Para registrar um span filho (por exemplo, uma chamada downstream na mesma requisição), chame Child() no rastreamento atual:

var trace = Trace.Current.Child();
Trace.Current = trace;
trace.Record(Annotations.ServerRecv());
trace.Record(Annotations.Rpc("server"));
trace.Record(Annotations.Tag("mytag", "spanSecond"));
trace.Record(Annotations.ServiceName("dotnetManual"));
// ... perform your operation here
trace.Record(Annotations.ServerSend());

(Opcional) Etapa 4: Adicionar tags personalizadas

Anexe tags personalizadas aos spans para facilitar a solução de problemas. Por exemplo, registre o código de status HTTP ou sinalize erros.

tracer.activeSpan().setTag("http.status_code", "200");

Etapa 5: Propagar o contexto de rastreamento entre serviços

Em sistemas distribuídos, o contexto de rastreamento acompanha cada requisição RPC para correlacionar spans de diferentes serviços em um único rastro. A biblioteca zipkin4net usa propagação B3 e transmite quatro valores via headers HTTP:

Campo de rastreamento	Header HTTP
TraceId	`X-B3-TraceId`
ParentSpanId	`X-B3-ParentSpanId`
SpanId	`X-B3-SpanId`
Sampled	`X-B3-Sampled`

Client Span                                                Server Span
┌──────────────────┐                                       ┌──────────────────┐
│                  │                                       │                  │
│   TraceContext   │           Http Request Headers        │   TraceContext   │
│ ┌──────────────┐ │          ┌───────────────────┐        │ ┌──────────────┐ │
│ │ TraceId      │ │          │ X-B3-TraceId      │        │ │ TraceId      │ │
│ │              │ │          │                   │        │ │              │ │
│ │ ParentSpanId │ │ Inject   │ X-B3-ParentSpanId │Extract │ │ ParentSpanId │ │
│ │              ├─┼─────────>│                   ├────────┼>│              │ │
│ │ SpanId       │ │          │ X-B3-SpanId       │        │ │ SpanId       │ │
│ │              │ │          │                   │        │ │              │ │
│ │ Sampled      │ │          │ X-B3-Sampled      │        │ │ Sampled      │ │
│ └──────────────┘ │          └───────────────────┘        │ └──────────────┘ │
│                  │                                       │                  │
└──────────────────┘                                       └──────────────────┘

Lado do cliente — injete o contexto de rastreamento nos headers da requisição de saída:

_injector.Inject(clientTrace.Trace.CurrentSpan, request.Headers);

Lado do servidor — extraia o contexto de rastreamento dos headers da requisição de entrada:

var traceContext = traceExtractor.Extract(context.Request.Headers);
var trace = traceContext == null ? Trace.Create() : Trace.CreateFromId(traceContext);

Se não houver contexto de rastreamento nos headers recebidos, um novo rastro raiz será criado. Caso contrário, o rastreamento existente continuará.

Perguntas frequentes

P: Por que nenhum dado aparece no console do Tracing Analysis após execute a demonstração?

R: Verifique se a URL do endpoint Zipkin na configuração do HttpZipkinSender está correta. Copie o endpoint diretamente do console do Tracing Analysis. A URL não deve incluir /api/v2/spans.

// Correct: use the base endpoint without /api/v2/spans
var httpSender = new HttpZipkinSender("http://tracing-analysis-dc-hz.aliyuncs.com/adapt_your_token", "application/json");