Use Jaeger for instrumentation and report .NET application data - Application Real-Time Monitoring Service

Importante

El cliente de Jaeger para C# ya no recibe mantenimiento. Utilice el SDK de OpenTelemetry para .NET en su lugar. Las siguientes instrucciones aplican únicamente a implementaciones existentes basadas en Jaeger.

Instrumente una aplicación .NET con Jaeger para reportar datos de rastreo a Managed Service for OpenTelemetry. Una vez que llegan los datos, la consola muestra la topología de la aplicación, trazas, transacciones anómalas y lentas, así como análisis de SQL.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

Jaeger 1.0.2
.NET 6.0 o .NET Core 3.1
Un endpoint de Jaeger obtenido desde la consola de Managed Service for OpenTelemetry (consulte la sección "Obtención del endpoint de Jaeger" más abajo)
El proyecto de ejemplo dotnet-demo clonado localmente

Arquitectura de reporte

Existen dos métodos disponibles para reportar datos de rastreo:

Reporte directo (sin Jaeger Agent):

不通过Jaeger Agent而直接上报

Reporte basado en agente (a través de Jaeger Agent):

通过Jaeger Agent上报数据

Contexto

Jaeger es un sistema de rastreo distribuido de código abierto creado por Uber. Es compatible con la API de OpenTracing y forma parte de la Cloud Native Computing Foundation (CNCF). Jaeger recopila datos de monitoreo en tiempo real provenientes de diversos sistemas heterogéneos.

La comunidad de OpenTracing proporciona componentes compatibles con los siguientes frameworks de .NET:

Obtención del endpoint de Jaeger

Inicie sesión en la consola de Managed Service for OpenTelemetry.
En el panel de navegación izquierdo, haga clic en Cluster Configurations. A continuación, seleccione la pestaña Access point information.
En la barra de navegación superior, seleccione una región. En la sección Cluster Information, active la opción Show Token.
En la sección Client, haga clic en Jaeger o Zipkin.
Copie el endpoint de la columna Related Information.

Jaeger/Zipkin access point information

Nota

Si su aplicación se ejecuta en un entorno de producción de Alibaba Cloud, utilice un endpoint de VPC. De lo contrario, use el endpoint público. Para Zipkin, utilice el endpoint v2 a menos que tenga una razón específica para usar v1.

Instrumentación de una aplicación .NET 6.0

Requisitos:

Jaeger 1.0.2
.NET 6.0

Configuración del tracer y ejecución del ejemplo

Paso 1: Configure el tracer de Jaeger.

Abra dotnet-demo/net6.0/Shared/JaegerServiceCollectionExtensions.cs y establezca el endpoint de Jaeger y el nombre de la aplicación:

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;
    }
}

Paso 2: Ejecute la aplicación de ejemplo.

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

Paso 3: Genere datos de rastreo.

Abra http://localhost:5001/health en un navegador.

Paso 4: Verificación.

Siga los pasos descritos en la sección "Verificación del reporte de datos de rastreo" más abajo.

Instrumentación de una aplicación .NET Core 3.1

Requisitos:

Jaeger 1.0.2
.NET Core 3.1

Para .NET Core 3.1 hay tres métodos de instrumentación disponibles:

Método	Cuándo utilizarlo
Middleware de ASP.NET Core	Aplicaciones web construidas sobre ASP.NET Core
Middleware de gRPC	Aplicaciones que usan gRPC para la comunicación entre servicios
Instrumentación manual	Necesidades de rastreo personalizadas o frameworks sin complementos existentes

Autoinstrumentación con ASP.NET Core

Paso 1: Configure el tracer de Jaeger.

Abra dotnet-demo/netcoreapp3.1/Shared/JaegerServiceCollectionExtensions.cs y configure el endpoint de Jaeger. La configuración es idéntica a la versión de .NET 6.0 mostrada anteriormente.

Paso 2: Instale el middleware de ASP.NET Core.

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

Paso 3: Instale el middleware en el proyecto de la aplicación y ejecútelo.

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

Paso 4: Genere datos de rastreo.

Abra http://localhost:5001/health en un navegador.

Paso 5: Verificación.

Siga los pasos descritos en la sección "Verificación del reporte de datos de rastreo" más abajo.

Autoinstrumentación con gRPC

La instrumentación de gRPC agrega rastreo tanto al lado del servidor como al del cliente en las llamadas gRPC.

Paso 1: Instale los paquetes NuGet.

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

Paso 2: Inicialice el 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();
}

Paso 3: Agregue la instrumentación del lado del servidor.

Construya un ServerTracingInterceptor y vincúlelo al servicio 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) }
};

Paso 4: Agregue la instrumentación del lado del cliente.

Construya un ClientTracingInterceptor y vincúlelo al 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));

Paso 5: Ejecute el servidor y el cliente.

Inicie el servidor gRPC en una terminal:

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

Inicie el cliente gRPC en otra terminal:

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

Si aparece Greeting: Hello you, la conexión funciona correctamente. Los datos de rastreo de dotnetGrpcServer y dotnetGrpcClient se están reportando ahora.

Instrumentación manual de una aplicación .NET

Utilice la instrumentación manual cuando los complementos existentes no cubran su caso de uso o cuando necesite un control detallado sobre qué operaciones se rastrean.

Paso 1: Instale los paquetes NuGet.

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

Paso 2: Construya el objeto ITracer.

La interfaz ITracer está definida por OpenTracing. Use la biblioteca de Jaeger para crear una implementación que especifique el endpoint y la configuración de muestreo:

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();
}

Paso 3: Registre el tracer globalmente.

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

Paso 4: Cree spans para registrar operaciones.

Cree un span raíz para la solicitud:

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 operaciones anidadas dentro de la misma solicitud, cree spans secundarios con 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();

Paso 5 (opcional): Agregue etiquetas personalizadas.

Adjunte metadatos a los spans para facilitar el filtrado y la depuración:

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

Paso 6: Propague el contexto entre servicios.

En un sistema distribuido, el contexto de rastreo (TraceId, ParentSpanId, SpanId, Sampled) viaja con cada solicitud de llamada a procedimiento remoto (RPC). Utilice Inject en el cliente y Extract en el servidor para pasar el contexto a través de encabezados HTTP.

Context propagation flow

Inyecte el contexto en el lado del cliente:

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

Extraiga el contexto en el lado del servidor:

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

Paso 7: Ejecute el ejemplo.

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

Los datos de rastreo de dotnetManualDemo aparecen en la consola de Managed Service for OpenTelemetry.

Verificación del reporte de datos de rastreo

Inicie sesión en la ARMS console.
En el panel de navegación izquierdo, elija Application Monitoring > Applications.
Busque su aplicación por nombre.

Nota

Si el icono Java图标 aparece en la columna Language, la aplicación está conectada a Application Monitoring. Un guion (-) indica una conexión a Managed Service for OpenTelemetry.

Preguntas frecuentes

No aparecen datos de rastreo tras ejecutar la demo

Compruebe que el endpoint en senderConfiguration sea correcto y accesible desde su entorno:

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");

Si su aplicación se ejecuta dentro de una VPC, asegúrese de estar utilizando el endpoint de VPC en lugar del público.

¿Cómo configuro la tasa de muestreo?

Para obtener más información, consulte la documentación del sampler de jaeger-client-csharp.

Pasos siguientes

Uso de OpenTelemetry para enviar datos de rastreo de aplicaciones .NET -- Migre al SDK de OpenTelemetry, que cuenta con mantenimiento activo.