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

Important

Le client Jaeger pour C# n'est plus maintenu. Utilisez le SDK OpenTelemetry pour .NET à la place. Les instructions ci-dessous s'appliquent uniquement aux implémentations existantes basées sur Jaeger.

Instrumentez une application .NET avec Jaeger pour envoyer les données de trace au service managé pour OpenTelemetry. Une fois les données reçues, la console affiche la topologie de l'application, les traces, les transactions anormales et lentes, ainsi que l'analyse SQL.

Prérequis

Avant de commencer, vérifiez que vous disposez des éléments suivants :

Jaeger 1.0.2
.NET 6.0 ou .NET Core 3.1
Un endpoint Jaeger obtenu depuis la console du service managé pour OpenTelemetry (voir la section « Obtenir l'endpoint Jaeger » ci-dessous)
Le projet d'exemple dotnet-demo cloné localement

Architecture de reporting

Deux méthodes permettent d'envoyer les données de trace :

Envoi direct (sans agent Jaeger) :

不通过Jaeger Agent而直接上报

Envoi via un agent (avec l'agent Jaeger) :

通过Jaeger Agent上报数据

Contexte

Jaeger est un système de traçage distribué open source créé par Uber. Il est compatible avec l'API OpenTracing et fait partie de la Cloud Native Computing Foundation (CNCF). Jaeger collecte des données de surveillance en temps réel provenant de divers systèmes hétérogènes.

La communauté OpenTracing fournit des composants qui prennent en charge les frameworks .NET suivants :

Obtenir l'endpoint Jaeger

Connectez-vous à la console du service managé pour OpenTelemetry.
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.
Copiez l'endpoint depuis la colonne Related Information.

Jaeger/Zipkin access point information

Remarque

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

Instrumenter une application .NET 6.0

Prérequis :

Jaeger 1.0.2
.NET 6.0

Configurer le traceur et exécuter l'exemple

Étape 1 : Configurez le traceur Jaeger.

Ouvrez dotnet-demo/net6.0/Shared/JaegerServiceCollectionExtensions.cs et définissez l'endpoint Jaeger ainsi que le nom de l'application :

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

Étape 2 : Exécutez l'application d'exemple.

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

Étape 3 : Générez des données de trace.

Ouvrez http://localhost:5001/health dans un navigateur.

Étape 4 : Vérifiez le résultat.

Suivez les étapes de la section « Vérifier le reporting des données de trace » ci-dessous.

Instrumenter une application .NET Core 3.1

Prérequis :

Jaeger 1.0.2
.NET Core 3.1

Trois méthodes d'instrumentation sont disponibles pour .NET Core 3.1 :

Méthode	Cas d'utilisation
Middleware ASP.NET Core	Applications web construites sur ASP.NET Core
Middleware gRPC	Applications utilisant gRPC pour la communication entre services
Instrumentation manuelle	Besoins de traçage personnalisés ou frameworks sans plug-ins existants

Auto-instrumentation avec ASP.NET Core

Étape 1 : Configurez le traceur Jaeger.

Ouvrez dotnet-demo/netcoreapp3.1/Shared/JaegerServiceCollectionExtensions.cs et définissez l'endpoint Jaeger. La configuration est identique à celle de la version .NET 6.0 présentée ci-dessus.

Étape 2 : Installez le middleware ASP.NET Core.

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

Étape 3 : Installez le middleware dans le projet d'application et exécutez-le.

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

Étape 4 : Générez des données de trace.

Ouvrez http://localhost:5001/health dans un navigateur.

Étape 5 : Vérifiez le résultat.

Suivez les étapes de la section « Vérifier le reporting des données de trace » ci-dessous.

Auto-instrumentation avec gRPC

L'instrumentation gRPC ajoute le traçage côté serveur et côté client des appels gRPC.

Étape 1 : Installez les packages NuGet.

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

Étape 2 : Initialisez le traceur.

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

Étape 3 : Ajoutez l'instrumentation côté serveur.

Créez un ServerTracingInterceptor et liez-le au service 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) }
};

Étape 4 : Ajoutez l'instrumentation côté client.

Créez un ClientTracingInterceptor et liez-le au 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));

Étape 5 : Exécutez le serveur et le client.

Démarrez le serveur gRPC dans un terminal :

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

Démarrez le client gRPC dans un autre terminal :

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

Si Greeting: Hello you s'affiche, la connexion fonctionne. Les données de trace de dotnetGrpcServer et dotnetGrpcClient sont désormais envoyées.

Instrumentation manuelle d'une application .NET

Utilisez l'instrumentation manuelle lorsque les plug-ins existants ne couvrent pas votre cas d'utilisation ou lorsque vous avez besoin d'un contrôle précis sur les opérations tracées.

Étape 1 : Installez les packages NuGet.

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

Étape 2 : Créez l'objet ITracer.

L'interface ITracer est définie par OpenTracing. Utilisez la bibliothèque Jaeger pour créer une implémentation qui spécifie l'endpoint et la configuration d'échantillonnage :

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

Étape 3 : Enregistrez le traceur globalement.

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

Étape 4 : Créez des spans pour enregistrer les opérations.

Créez une span racine pour la requête :

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

Pour enregistrer des opérations imbriquées au sein de la même requête, créez des spans enfants avec 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();

Étape 5 (facultative) : Ajoutez des tags personnalisés.

Attachez des métadonnées aux spans pour le filtrage et le débogage :

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

Étape 6 : Propagez le contexte entre les services.

Dans un système distribué, le contexte de trace (TraceId, ParentSpanId, SpanId, Sampled) accompagne chaque appel de procédure distante (RPC). Utilisez Inject côté client et Extract côté serveur pour transmettre le contexte via les en-têtes HTTP.

Context propagation flow

Injectez le contexte côté client :

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

Extrayez le contexte côté serveur :

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

Étape 7 : Exécutez l'exemple.

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

Les données de trace de dotnetManualDemo apparaissent dans la console du service managé pour OpenTelemetry.

Vérifier le reporting des données de trace

Connectez-vous à la console ARMS.
Dans le volet de navigation de gauche, choisissez Application Monitoring > Applications.
Recherchez votre application par son nom.

Remarque

Si l'icône Java图标 apparaît dans la colonne Language, l'application est connectée à Application Monitoring. Un tiret (-) indique une connexion au service managé pour OpenTelemetry.

FAQ

Aucune donnée de trace n'apparaît après l'exécution de la démo

Vérifiez que l'endpoint dans senderConfiguration est correct et accessible depuis votre environnement :

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 votre application s'exécute dans un VPC, assurez-vous d'utiliser l'endpoint VPC plutôt que l'endpoint public.

Comment configurer le taux d'échantillonnage ?

Pour plus d'informations, consultez la documentation sur l'échantillonneur jaeger-client-csharp.

Étapes suivantes

Utiliser OpenTelemetry pour soumettre les données de trace des applications .NET — Migrez vers le SDK OpenTelemetry activement maintenu.