Todos os produtos
Search

Este produto

    Application Real-Time Monitoring Service:Report .NET application data through Zipkin

    Central de documentação

    Application Real-Time Monitoring Service:Report .NET application data through Zipkin

    Última atualização: Jul 05, 2026

    O Zipkin é um sistema de rastreamento distribuído de código aberto desenvolvido originalmente pelo Twitter. Ele agrega dados de monitoramento em tempo real de vários sistemas heterogêneos. Use a biblioteca zipkin4net para instrumentar aplicativos .NET e relatar dados de rastreamento ao Application Real-Time Monitoring Service (ARMS) Tracing Analysis.

    Este tópico aborda três métodos de instrumentação para aplicativos .NET e C#.

    Escolha um método de instrumentação

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

    Método

    Indicado para

    Pacotes NuGet necessários

    ASP.NET Core

    Aplicativos web multiplataforma desenvolvidos com ASP.NET Core

    zipkin4net.middleware.aspnetcore, zipkin4net

    OWIN

    Aplicativos web .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)

    Obtenha um endpoint do Zipkin

    1. Faça login no console do Tracing Analysis.

    2. No painel de navegação à esquerda, clique em Cluster Configurations. Em seguida, clique na guia Access point information.

    3. Na barra de navegação superior, selecione uma região. Na seção Cluster Information, ative Show Token.

    4. Na seção Client, clique em Jaeger ou Zipkin.

    5. 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. Utilize o endpoint v2, a menos que tenha um motivo específico para usar a versão v1.

    Instrumente com ASP.NET Core

    Nota

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

    Etapa 1: Instale os pacotes NuGet

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

    Pacote

    Finalidade

    zipkin4net

    Biblioteca principal de rastreamento. Cria spans, gerencia amostragem e relata dados de rastreamento para um backend compatível com Zipkin.

    zipkin4net.middleware.aspnetcore

    Middleware para ASP.NET Core. Cria automaticamente um span de servidor para cada requisição HTTP recebida.

    Etapa 2: Registre e inicie o rastreador

    Adicione o código abaixo à lógica de inicialização do aplicativo para configurar 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: Rastreie requisições HTTP de saída

    Adicione o TracingHandler ao pipeline do HttpClient para rastrear automaticamente as chamadas HTTP de saída e correlacioná-las ao span pai.

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

    Instrumente com OWIN

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

    Nota

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

    Etapa 1: Instale os 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. Cria automaticamente um span de servidor para cada requisição HTTP recebida.

    Etapa 2: Registre e inicie o rastreador

    // 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: Rastreie 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);
}

    Instrumente manualmente

    Use a instrumentação manual para ter controle total sobre a criação de spans — por exemplo, ao 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: Registre e inicie o rastreador

    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 registre spans

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

    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 o método 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: Adicione 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: Propague o contexto de rastreamento entre serviços

    Em sistemas distribuídos, o contexto de rastreamento viaja com cada requisição RPC para correlacionar spans de diferentes serviços em um único rastreamento. A biblioteca zipkin4net usa a propagação B3, transmitindo quatro valores por cabeçalhos HTTP:

    Campo de rastreamento

    Cabeçalho 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 cabeçalhos da requisição de saída:

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

    Lado do servidor — extraia o contexto de rastreamento dos cabeçalhos 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 cabeçalhos recebidos, um novo rastreamento 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 executar a demonstração?

    R: Verifique se a URL do endpoint do 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");