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

Zipkin est un système de traçage distribué open source développé à l'origine par Twitter. Il agrège des données de surveillance en temps réel provenant de plusieurs systèmes hétérogènes. Utilisez la bibliothèque zipkin4net pour instrumenter les applications .NET et envoyer les données de trace au service Tracing Analysis d'Application Real-Time Monitoring Service (ARMS).

Cette rubrique présente trois méthodes d'instrumentation pour les applications .NET et C#.

Choisir une méthode d'instrumentation

Sélectionnez la méthode adaptée à votre framework d'application.

Méthode	Idéale pour	Packages NuGet requis
ASP.NET Core	Applications web multiplateformes basées sur ASP.NET Core	`zipkin4net.middleware.aspnetcore`, `zipkin4net`
OWIN	Applications web .NET Framework utilisant le middleware OWIN	`zipkin4net.middleware.aspnetcore`, `zipkin4net`
Manuelle	Tâches en arrière-plan, consommateurs de messages ou protocoles personnalisés nécessitant un contrôle précis des spans	`zipkin4net`

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

Un compte Alibaba Cloud avec ARMS activé
Un environnement de développement .NET
L'endpoint Zipkin de votre instance Tracing Analysis ARMS (voir Obtenir un endpoint Zipkin)

Obtenir un endpoint Zipkin

Connectez-vous à la console Tracing Analysis.
Dans le volet de navigation de gauche, cliquez sur Cluster Configurations. Ensuite, cliquez sur l'onglet Access point information.
Dans la barre de navigation supérieure, sélectionnez une région. Dans la section Cluster Information, activez l'option Show Token.
Dans la section Client, cliquez sur Jaeger ou Zipkin.
Dans la colonne Related Information, copiez l'URL de l'endpoint.

Endpoint of Jaeger or Zipkin

Remarque

Si votre application s'exécute dans un environnement de production Alibaba Cloud, utilisez un point d'accès VPC. Sinon, utilisez un endpoint public. Privilégiez l'endpoint v2, sauf si vous avez une raison spécifique d'utiliser la version v1.

Instrumenter avec ASP.NET Core

Remarque

Téléchargez le projet de démonstration complet et suivez les instructions du fichier README.md.

Étape 1 : Installer les packages NuGet

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

Package	Objectif
`zipkin4net`	Bibliothèque de traçage principale. Crée des spans, gère l'échantillonnage et envoie les données de trace à un backend compatible Zipkin.
`zipkin4net.middleware.aspnetcore`	Middleware ASP.NET Core. Crée automatiquement une span serveur pour chaque requête HTTP entrante.

Étape 2 : Enregistrer et démarrer le traceur

Ajoutez le code suivant à la logique de démarrage de votre application pour configurer zipkin4net et le connecter à votre endpoint Tracing Analysis ARMS.

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

Remplacez l'espace réservé suivant par votre valeur réelle :

Espace réservé	Description	Exemple
`<your-zipkin-endpoint>`	Endpoint Zipkin issu de la console Tracing Analysis	`http://tracing-analysis-dc-hz.aliyuncs.com/adapt_your_token`

Étape 3 : Tracer les requêtes HTTP sortantes

Ajoutez TracingHandler à votre pipeline HttpClient afin que les appels HTTP sortants soient automatiquement tracés et corrélés avec la span parente.

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

Instrumenter avec OWIN

Open Web Interface for .NET (OWIN) est une spécification de middleware pour les applications web .NET Framework.

Remarque

Téléchargez le projet de démonstration complet et suivez les instructions du fichier README.md.

Étape 1 : Installer les packages NuGet

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

Package	Objectif
`zipkin4net`	Bibliothèque de traçage principale.
`zipkin4net.middleware.aspnetcore`	Middleware ASP.NET Core. Crée automatiquement une span serveur pour chaque requête HTTP entrante.

Étape 2 : Enregistrer et démarrer le traceur

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

Étape 3 : Tracer les requêtes HTTP sortantes

Enveloppez votre HttpClient avec TracingHandler pour propager le contexte de trace au-delà des limites de service.

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

Instrumenter manuellement

Utilisez l'instrumentation manuelle pour contrôler entièrement la création des spans, par exemple pour tracer des tâches en arrière-plan, des consommateurs de messages ou des protocoles personnalisés.

Remarque

Téléchargez le projet de démonstration complet et suivez les instructions du fichier README.md.

Étape 1 : Installer le package NuGet

Seule la bibliothèque de traçage principale est requise pour l'instrumentation manuelle.

dotnet add package zipkin4net

Étape 2 : Enregistrer et démarrer le traceur

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

Étape 3 : Créer et enregistrer des spans

Créez une span racine pour chaque requête ou opération, puis enregistrez ses événements de cycle de vie.

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

Pour enregistrer une span enfant (par exemple, un appel descendant au sein de la même requête), appelez Child() sur la trace actuelle :

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

(Facultatif) Étape 4 : Ajouter des tags personnalisés

Attachez des tags personnalisés aux spans pour faciliter le dépannage. Par exemple, enregistrez le code d'état HTTP ou signalez les erreurs.

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

Étape 5 : Propager le contexte de trace entre les services

Dans un système distribué, le contexte de trace accompagne chaque requête RPC afin que les spans de différents services soient corrélées en une seule trace. La bibliothèque zipkin4net utilise la propagation B3, qui transmet quatre valeurs via les en-têtes HTTP :

Champ de trace	En-tête 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      │ │
│ └──────────────┘ │          └───────────────────┘        │ └──────────────┘ │
│                  │                                       │                  │
└──────────────────┘                                       └──────────────────┘

Côté client -- injectez le contexte de trace dans les en-têtes de requête sortants :

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

Côté serveur -- extrayez le contexte de trace des en-têtes de requête entrants :

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

Lorsqu'aucun contexte de trace n'est présent dans les en-têtes entrants, une nouvelle trace racine est créée. Sinon, la trace existante se poursuit.

FAQ

Q : Pourquoi aucune donnée n'apparaît dans la console Tracing Analysis après l'exécution de la démo ?

R : Vérifiez que l'URL de l'endpoint Zipkin dans votre configuration HttpZipkinSender est correcte. Copiez l'endpoint directement depuis la console Tracing Analysis. L'URL ne doit pas inclure /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");