Use Jaeger for instrumentation and report .NET application data - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

Importante

O cliente Jaeger para C# não recebe mais manutenção. Use o SDK do OpenTelemetry para .NET. As instruções abaixo aplicam-se apenas a implementações existentes baseadas no Jaeger.

Instrumente uma aplicação .NET com o Jaeger para relatar dados de rastreamento ao Managed Service for OpenTelemetry. Após o recebimento dos dados, o console exibe a topologia da aplicação, traces, transações anômalas e lentas, além de análises de SQL.

Pré-requisitos

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

Jaeger 1.0.2
.NET 6.0 ou .NET Core 3.1
Um endpoint do Jaeger obtido no console do Managed Service for OpenTelemetry (consulte a seção "Obter o endpoint do Jaeger" abaixo)
O projeto de exemplo dotnet-demo clonado localmente

Arquitetura de relatórios

Há dois métodos disponíveis para relatar dados de rastreamento:

Relatório direto (sem o Jaeger Agent):

不通过Jaeger Agent而直接上报

Relatório baseado em agente (por meio do Jaeger Agent):

通过Jaeger Agent上报数据

Informações de contexto

O Jaeger é um sistema de rastreamento distribuído de código aberto criado pela Uber. Ele é compatível com a API OpenTracing e membro da Cloud Native Computing Foundation (CNCF). O Jaeger coleta dados de monitoramento em tempo real de diversos sistemas heterogêneos.

A comunidade OpenTracing fornece componentes compatíveis com os seguintes frameworks .NET:

Obter o endpoint do Jaeger

Faça login no console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Cluster Configurations. Em seguida, clique em 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.
Copie o endpoint da coluna Related Information.

Jaeger/Zipkin access point information

Nota

Se sua aplicação for executada em um ambiente de produção da Alibaba Cloud, use um endpoint de VPC. Caso contrário, use o endpoint público. Para o Zipkin, use o endpoint v2, a menos que haja um motivo específico para usar a versão v1.

Instrumentar uma aplicação .NET 6.0

Requisitos:

Jaeger 1.0.2
.NET 6.0

Configurar o tracer e executar o exemplo

Etapa 1: Configure o tracer do Jaeger.

Abra o arquivo dotnet-demo/net6.0/Shared/JaegerServiceCollectionExtensions.cs e defina o endpoint do Jaeger e o nome da aplicação:

public static class JaegerServiceCollectionExtensions
{
    // Replace with your Jaeger endpoint. See "Get the Jaeger endpoint" above.
    private static readonly Uri _jaegerUri = new Uri("http://tracing-analysis-dc-sz.aliyuncs.com/adapt_your_token/api/traces");

    public static IServiceCollection AddJaeger(this IServiceCollection services)
    {
        if (services == null)
            throw new ArgumentNullException(nameof(services));

        services.AddSingleton<ITracer>(serviceProvider =>
        {
            // Uses the assembly name as the service name.
            string serviceName = Assembly.GetEntryAssembly().GetName().Name;

            ILoggerFactory loggerFactory = serviceProvider.GetRequiredService<ILoggerFactory>();

            ISampler sampler = new ConstSampler(sample: true);

            IReporter reporter = new RemoteReporter.Builder()
                .WithSender(new HttpSender.Builder(_jaegerUri.ToString()).Build())
                .Build();

            ITracer tracer = new Tracer.Builder(serviceName)
                .WithLoggerFactory(loggerFactory)
                .WithSampler(sampler)
                .WithReporter(reporter)
                .Build();

            GlobalTracer.Register(tracer);

            return tracer;
        });

        // Prevent endless loops when OpenTracing tracks HTTP requests to Jaeger.
        services.Configure<HttpHandlerDiagnosticOptions>(options =>
        {
            options.IgnorePatterns.Add(request => _jaegerUri.IsBaseOf(request.RequestUri));
        });

        return services;
    }
}

Etapa 2: Execute a aplicação de exemplo.

cd dotnet-demo/net6.0/CustomersApi
dotnet run --framework:net6.0

Etapa 3: Gere dados de rastreamento.

Acesse http://localhost:5001/health em um navegador.

Etapa 4: Verifique.

Siga as etapas na seção "Verificar o relatório de dados de rastreamento" abaixo.

Instrumentar uma aplicação .NET Core 3.1

Requisitos:

Jaeger 1.0.2
.NET Core 3.1

Três métodos de instrumentação estão disponíveis para o .NET Core 3.1:

Método	Quando usar
Middleware do ASP.NET Core	Aplicações web desenvolvidas com ASP.NET Core
Middleware gRPC	Aplicações que usam gRPC para comunicação entre serviços
Instrumentação manual	Necessidades personalizadas de rastreamento ou frameworks sem plug-ins disponíveis

Auto-instrumentar com ASP.NET Core

Etapa 1: Configure o tracer do Jaeger.

Abra o arquivo dotnet-demo/netcoreapp3.1/Shared/JaegerServiceCollectionExtensions.cs e defina o endpoint do Jaeger. A configuração é idêntica à versão .NET 6.0 apresentada acima.

Etapa 2: Instale o middleware do ASP.NET Core.

cd dotnet-demo/netcoreapp3.1/Shared
dotnet add package OpenTracing.Contrib.NetCore

Etapa 3: Instale o middleware no projeto da aplicação e execute-o.

cd dotnet-demo/netcoreapp3.1/CustomersApi
dotnet add package OpenTracing.Contrib.NetCore
dotnet run --framework:netcoreapp3.1

Etapa 4: Gere dados de rastreamento.

Acesse http://localhost:5001/health em um navegador.

Etapa 5: Verifique.

Siga as etapas na seção "Verificar o relatório de dados de rastreamento" abaixo.

Auto-instrumentar com gRPC

A instrumentação gRPC adiciona rastreamento tanto no lado do servidor quanto no lado do cliente das chamadas gRPC.

Etapa 1: Instale os pacotes NuGet.

dotnet add package OpenTracing.Contrib.grpc
dotnet add package Jaeger

Etapa 2: Inicialize o tracer.

public static Tracer InitTracer(string serviceName, ILoggerFactory loggerFactory)
{
    Configuration.SamplerConfiguration samplerConfiguration = new Configuration.SamplerConfiguration(loggerFactory)
        .WithType(ConstSampler.Type)
        .WithParam(1);
    Configuration.SenderConfiguration senderConfiguration = new Configuration.SenderConfiguration(loggerFactory)
        // Replace with your Jaeger endpoint. See "Get the Jaeger endpoint" above.
        .WithEndpoint("http://tracing-analysis-dc-sz.aliyuncs.com/adapt_your_token/api/traces");
    Configuration.ReporterConfiguration reporterConfiguration = new Configuration.ReporterConfiguration(loggerFactory)
        .WithSender(senderConfiguration);

    return (Tracer)new Configuration(serviceName, loggerFactory)
        .WithSampler(samplerConfiguration)
        .WithReporter(reporterConfiguration)
        .GetTracer();
}

Etapa 3: Adicione a instrumentação no lado do servidor.

Crie um ServerTracingInterceptor e vincule-o ao serviço gRPC:

ILoggerFactory loggerFactory = new LoggerFactory().AddConsole();
ITracer tracer = TracingHelper.InitTracer("dotnetGrpcServer", loggerFactory);
ServerTracingInterceptor tracingInterceptor = new ServerTracingInterceptor(tracer);
Server server = new Server
{
    Services = { Greeter.BindService(new GreeterImpl()).Intercept(tracingInterceptor) },
    Ports = { new ServerPort("localhost", Port, ServerCredentials.Insecure) }
};

Etapa 4: Adicione a instrumentação no lado do cliente.

Crie um ClientTracingInterceptor e vincule-o ao canal:

ILoggerFactory loggerFactory = new LoggerFactory().AddConsole();
ITracer tracer = TracingHelper.InitTracer("dotnetGrpcClient", loggerFactory);
ClientTracingInterceptor tracingInterceptor = new ClientTracingInterceptor(tracer);
Channel channel = new Channel("127.0.0.1:50051", ChannelCredentials.Insecure);

var client = new Greeter.GreeterClient(channel.Intercept(tracingInterceptor));

Etapa 5: Execute o servidor e o cliente.

Inicie o servidor gRPC em um terminal:

cd dotnet-demo/netcoreapp3.1/GreeterServer
dotnet run --framework:netcoreapp3.1

Inicie o cliente gRPC em outro terminal:

cd dotnet-demo/netcoreapp3.1/GreeterClient
dotnet run --framework:netcoreapp3.1

Se a mensagem Greeting: Hello you aparecer, a conexão estará funcionando corretamente. Os dados de rastreamento de dotnetGrpcServer e dotnetGrpcClient agora são relatados.

Instrumentar manualmente uma aplicação .NET

Use a instrumentação manual quando os plug-ins existentes não atenderem ao seu caso de uso ou quando for necessário controle refinado sobre quais operações rastrear.

Etapa 1: Instale os pacotes NuGet.

dotnet add package Microsoft.Extensions.Logging.Console
dotnet add package Jaeger

Etapa 2: Construa o objeto ITracer.

A interface ITracer é definida pelo OpenTracing. Use a biblioteca do Jaeger para criar uma implementação que especifique o endpoint e a configuração de amostragem:

public static ITracer InitTracer(string serviceName, ILoggerFactory loggerFactory)
{
    Configuration.SamplerConfiguration samplerConfiguration = new Configuration.SamplerConfiguration(loggerFactory)
        .WithType(ConstSampler.Type)
        .WithParam(1);
    Configuration.SenderConfiguration senderConfiguration = new Configuration.SenderConfiguration(loggerFactory)
        // Replace with your Jaeger endpoint. See "Get the Jaeger endpoint" above.
        .WithEndpoint("http://tracing-analysis-dc-sz.aliyuncs.com/adapt_your_token/api/traces");

    Configuration.ReporterConfiguration reporterConfiguration = new Configuration.ReporterConfiguration(loggerFactory)
        .WithSender(senderConfiguration);

    return (Tracer)new Configuration(serviceName, loggerFactory)
        .WithSampler(samplerConfiguration)
        .WithReporter(reporterConfiguration)
        .GetTracer();
}

Etapa 3: Registre o tracer globalmente.

GlobalTracer.Register(InitTracer("dotnetManualDemo", loggerFactory));

Etapa 4: Crie spans para registrar operações.

Crie um span raiz para a requisição:

ITracer tracer = GlobalTracer.Instance;
ISpan span = tracer.BuildSpan("parentSpan").WithTag("mytag", "parentSpan").Start();
tracer.ScopeManager.Activate(span, false);
// ... your business logic here
span.Finish();

Para registrar operações aninhadas na mesma requisição, crie spans filhos com AsChildOf:

ITracer tracer = GlobalTracer.Instance;
ISpan parentSpan = tracer.ActiveSpan;
ISpan childSpan = tracer.BuildSpan("childSpan").AsChildOf(parentSpan).WithTag("mytag", "spanSecond").Start();
tracer.ScopeManager.Activate(childSpan, false);
// ... your business logic here
childSpan.Finish();

Etapa 5 (opcional): Adicione tags personalizadas.

Anexe metadados aos spans para facilitar filtragem e depuração:

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

Etapa 6: Propague o contexto entre serviços.

Em um sistema distribuído, o contexto de rastreamento (TraceId, ParentSpanId, SpanId, Sampled) acompanha cada requisição de chamada de procedimento remoto (RPC). Use Inject no cliente e Extract no servidor para transmitir o contexto por cabeçalhos HTTP.

Context propagation flow

Injete o contexto no lado do cliente:

Tracer.Inject(span.Context, BuiltinFormats.HttpHeaders, new HttpHeadersInjectAdapter(request.Headers));

Extraia o contexto no lado do servidor:

ISpanContext extractedSpanContext = _tracer.Extract(BuiltinFormats.HttpHeaders, new RequestHeadersExtractAdapter(request.Headers));
ISpan childSpan = _tracer.BuildSpan(operationName).AsChildOf(extractedSpanContext);

Etapa 7: Execute o exemplo.

cd dotnet-demo/netcoreapp3.1/ManualDemo
dotnet run --framework:netcoreapp3.1

Os dados de rastreamento de dotnetManualDemo aparecem no console do Managed Service for OpenTelemetry.

Verificar o relatório de dados de rastreamento

Faça login no console do ARMS.
No painel de navegação à esquerda, escolha Application Monitoring > Applications.
Pesquise sua aplicação pelo nome.

Nota

Se o ícone Java图标 aparecer na coluna Language, a aplicação está conectada ao Application Monitoring. Um hífen (-) indica conexão com o Managed Service for OpenTelemetry.

Perguntas frequentes

Nenhum dado de rastreamento aparece após executar a demonstração

Verifique se o endpoint em senderConfiguration está correto e acessível no seu ambiente:

Configuration.SenderConfiguration senderConfiguration = new Configuration.SenderConfiguration(loggerFactory)
    // Verify this endpoint matches the one from the console.
    .WithEndpoint("http://tracing-analysis-dc-sz.aliyuncs.com/adapt_your_token/api/traces");

Se sua aplicação for executada em uma VPC, certifique-se de usar o endpoint de VPC em vez do endpoint público.

Como configuro a taxa de amostragem?

Para mais informações, consulte a documentação do sampler do jaeger-client-csharp.

Próximos passos

Usar o OpenTelemetry para enviar dados de rastreamento de aplicações .NET -- Migre para o SDK do OpenTelemetry, que possui manutenção ativa.