Instrument .NET applications and report traces using Zipkin - Application Real-Time Monitoring Service

Zipkin es un sistema de rastreo distribuido de código abierto desarrollado originalmente por Twitter. Este sistema agrega datos de monitoreo en tiempo real provenientes de varios sistemas heterogéneos. Puede utilizar la biblioteca zipkin4net para instrumentar aplicaciones .NET y enviar datos de rastreo a Application Real-Time Monitoring Service (ARMS) Tracing Analysis.

Este tema aborda tres métodos de instrumentación para aplicaciones .NET y C#.

Elección del método de instrumentación

Seleccione el método que corresponda al framework de su aplicación.

Método	Recomendado para	Paquetes NuGet obligatorios
ASP.NET Core	Aplicaciones web multiplataforma basadas en ASP.NET Core	`zipkin4net.middleware.aspnetcore`, `zipkin4net`
OWIN	Aplicaciones web de .NET Framework que usan middleware OWIN	`zipkin4net.middleware.aspnetcore`, `zipkin4net`
Manual	Tareas en segundo plano, consumidores de mensajes o protocolos personalizados que requieren un control detallado de los spans	`zipkin4net`

Requisitos previos

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

Una cuenta de Alibaba Cloud con ARMS activado
Un entorno de desarrollo .NET
El endpoint de Zipkin correspondiente a su instancia de ARMS Tracing Analysis (consulte Obtención de un endpoint de Zipkin)

Obtención de un endpoint de Zipkin

Inicie sesión en la consola de Tracing Analysis.
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.
En la columna Related Information, copie la URL del endpoint.

Endpoint of Jaeger or Zipkin

Nota

Si su aplicación se ejecuta en un entorno de producción de Alibaba Cloud, utilice un punto de acceso VPC. De lo contrario, use un endpoint público. Se recomienda emplear el endpoint v2, salvo que tenga un motivo específico para usar v1.

Instrumentación con ASP.NET Core

Nota

Descargue el proyecto de demostración completo y siga las instrucciones incluidas en su archivo README.md.

Paso 1: Instalación de paquetes NuGet

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

Paquete	Propósito
`zipkin4net`	Biblioteca base de rastreo. Crea spans, gestiona el muestreo y envía los datos de rastreo a un backend compatible con Zipkin.
`zipkin4net.middleware.aspnetcore`	Middleware para ASP.NET Core. Genera automáticamente un span de servidor por cada solicitud HTTP entrante.

Paso 2: Registro e inicio del rastreador

Agregue el siguiente código a la lógica de inicio de su aplicación para configurar zipkin4net y conectarlo con su endpoint de 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);

Reemplace el siguiente marcador de posición con su valor real:

Marcador de posición	Descripción	Ejemplo
`<your-zipkin-endpoint>`	Endpoint de Zipkin obtenido desde la consola de Tracing Analysis	`http://tracing-analysis-dc-hz.aliyuncs.com/adapt_your_token`

Paso 3: Rastreo de solicitudes HTTP salientes

Agregue TracingHandler a la canalización de su HttpClient para que las llamadas HTTP salientes se rastreen automáticamente y se correlacionen con el span principal.

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

Instrumentación con OWIN

Open Web Interface for .NET (OWIN) es una especificación de middleware diseñada para aplicaciones web de .NET Framework.

Nota

Descargue el proyecto de demostración completo y siga las instrucciones incluidas en su archivo README.md.

Paso 1: Instalación de paquetes NuGet

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

Paquete	Propósito
`zipkin4net`	Biblioteca base de rastreo.
`zipkin4net.middleware.aspnetcore`	Middleware para ASP.NET Core. Genera automáticamente un span de servidor por cada solicitud HTTP entrante.

Paso 2: Registro e inicio del 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"]);

Paso 3: Rastreo de solicitudes HTTP salientes

Envuelva su HttpClient con TracingHandler para propagar el contexto de rastreo entre los límites de los servicios.

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

Instrumentación manual

Utilice la instrumentación manual cuando necesite control total sobre la creación de spans; por ejemplo, para rastrear tareas en segundo plano, consumidores de mensajes o protocolos personalizados.

Nota

Descargue el proyecto de demostración completo y siga las instrucciones incluidas en su archivo README.md.

Paso 1: Instalación del paquete NuGet

Para la instrumentación manual solo se requiere la biblioteca base de rastreo.

dotnet add package zipkin4net

Paso 2: Registro e inicio del 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);

Paso 3: Creación y registro de spans

Cree un span raíz para cada solicitud u operación y registre sus 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 un span secundario (por ejemplo, una llamada descendente dentro de la misma solicitud), invoque Child() sobre el rastreo actual:

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) Paso 4: Adición de etiquetas personalizadas

Adjunte etiquetas personalizadas a los spans para facilitar la resolución de problemas. Por ejemplo, registre el código de estado HTTP o marque errores.

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

Paso 5: Propagación del contexto de rastreo entre servicios

En un sistema distribuido, el contexto de rastreo viaja con cada solicitud RPC para que los spans de distintos servicios se correlacionen en un único rastreo. La biblioteca zipkin4net utiliza la propagación B3 y transmite cuatro valores mediante encabezados HTTP:

Campo de rastreo	Encabezado 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 del cliente: inyecte el contexto de rastreo en los encabezados de la solicitud saliente:

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

Lado del servidor: extraiga el contexto de rastreo de los encabezados de la solicitud entrante:

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

Si no existe un contexto de rastreo en los encabezados entrantes, se crea un nuevo rastreo raíz. En caso contrario, continúa el rastreo existente.

Preguntas frecuentes

P: ¿Por qué no aparecen datos en la consola de Tracing Analysis después de ejecutar la demostración?

R: Compruebe que la URL del endpoint de Zipkin en la configuración de su HttpZipkinSender sea correcta. Copie el endpoint directamente desde la consola de Tracing Analysis. La URL no debe 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");