Journalisation et diagnostics dans gRPC sur .NET

Par James Newton-King

Cet article fournit des conseils pour la collecte de diagnostics à partir d’une application gRPC pour vous aider à résoudre les problèmes. Sont abordés les sujets suivants :

• Journalisation : journaux structurés écrits dans la journalisation .NET Core. ILogger est utilisé par les frameworks d’application pour écrire des journaux, et par les utilisateurs pour leur propre journalisation dans une application.
• Suivi : événements liés à une opération écrite à l’aide de DiaganosticSource et Activity. Les traces de la source de diagnostic sont couramment utilisées pour collecter les données de télémétrie des applications par des bibliothèques comme Application Insights et OpenTelemetry.
• Métriques : représentation des mesures de données sur des intervalles de temps, par exemple, le nombre de requêtes par seconde. Les métriques sont émises à l’aide de EventCounter et peuvent être observées à l’aide de l’outil en ligne de commande dotnet-counters ou avec Application Insights.

Journalisation

Les services gRPC et le client gRPC écrivent des journaux à l’aide de la journalisation .NET Core. Les journaux sont un bon point de départ lors du débogage d’un comportement inattendu dans les applications clientes et de service.

Journalisation des services gRPC

Avertissement

Les journaux côté serveur peuvent contenir des informations sensibles de votre application. Ne publiez jamais les journaux bruts des applications de production sur des forums publics comme GitHub.

Étant donné que les services gRPC sont hébergés sur ASP.NET Core, ils utilisent le système de journalisation ASP.NET Core. Dans la configuration par défaut, gRPC consigne des informations minimales, mais la journalisation peut être configurée. Pour plus d’informations sur la configuration de la journalisation ASP.NET Core, consultez la documentation sur la Journalisation ASP.NET Core.

gRPC ajoute des journaux sous la catégorie Grpc. Pour activer les journaux détaillés à partir de gRPC, configurez les préfixes Grpc au niveau Debug dans le fichier appsettings.json en ajoutant les éléments suivants à la sous-section LogLevel dans Logging :

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information",
      "Grpc": "Debug"
    }
  }
}

La journalisation peut également être configurée dans Program.cs avec ConfigureLogging :

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.AddFilter("Grpc", LogLevel.Debug);
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Lorsque vous n’utilisez pas la configuration basée sur JSON, définissez la valeur de configuration suivante dans le système de configuration :

• Logging:LogLevel:Grpc = Debug

Consultez la documentation de votre système de configuration pour déterminer comment spécifier des valeurs de configuration imbriquées. Par exemple, lors de l’utilisation de variables d’environnement, deux caractères _ sont utilisés à la place de : (par exemple Logging__LogLevel__Grpc).

Nous vous recommandons d’utiliser le niveau Debug lors de la collecte de diagnostics détaillées pour une application. Le niveau Trace produit des diagnostics de bas niveau et est rarement nécessaire pour diagnostiquer les problèmes.

Exemple de sortie de la journalisation

Voici un exemple de sortie de console au niveau Debug d’un service gRPC :

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 POST https://localhost:5001/Greet.Greeter/SayHello application/grpc
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'gRPC - /Greet.Greeter/SayHello'
dbug: Grpc.AspNetCore.Server.ServerCallHandler[1]
      Reading message.
info: GrpcService.GreeterService[0]
      Hello World
dbug: Grpc.AspNetCore.Server.ServerCallHandler[6]
      Sending message.
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'gRPC - /Greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 1.4113ms 200 application/grpc

Accéder aux journaux côté serveur

L’accès aux journaux côté serveur dépend de l’environnement de l’application.

En tant qu’application console

Si vous exécutez dans une application console, l’enregistreur d’événements de console doit être activé par défaut. Les journaux gRPC s’affichent dans la console.

Autres environnements

Si l’application est déployée dans un autre environnement (par exemple, Docker, Kubernetes ou Windows Service), consultez Journalisation dans .NET Core et ASP.NET Core pour plus d’informations sur la configuration des fournisseurs de journalisation adaptés à l’environnement.

Journalisation du client gRPC

Avertissement

Les journaux côté client peuvent contenir des informations sensibles de votre application. Ne publiez jamais les journaux bruts des applications de production sur des forums publics comme GitHub.

Pour obtenir les journaux à partir du client .NET, définissez la propriété GrpcChannelOptions.LoggerFactory lors de la création du canal du client. Lors de l’appel d’un service gRPC à partir d’une application ASP.NET Core, la fabrique d’enregistreurs d’événements peut être résolue à partir de l’injection de dépendances (DI) :

[ApiController]
[Route("[controller]")]
public class GreetingController : ControllerBase
{
    private ILoggerFactory _loggerFactory;

    public GreetingController(ILoggerFactory loggerFactory)
    {
        _loggerFactory = loggerFactory;
    }

    [HttpGet]
    public async Task<ActionResult<string>> Get(string name)
    {
        var channel = GrpcChannel.ForAddress("https://localhost:5001",
            new GrpcChannelOptions { LoggerFactory = _loggerFactory });
        var client = new Greeter.GreeterClient(channel);

        var reply = await client.SayHelloAsync(new HelloRequest { Name = name });
        return Ok(reply.Message);
    }
}

Une autre façon d’activer la journalisation des clients consiste à utiliser la fabrique de clients gRPC pour créer le client. Un client gRPC inscrit auprès de la fabrique du client et résolu à partir de la DI utilise automatiquement la journalisation configurée de l’application.

Si l’application n’utilise pas de DI, créez un instance de ILoggerFactory avec LoggerFactory.Create. Pour accéder à cette méthode, ajoutez le package Microsoft.Extensions.Logging à votre application.

var loggerFactory = LoggerFactory.Create(logging =>
{
    logging.AddConsole();
    logging.SetMinimumLevel(LogLevel.Debug);
});

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { LoggerFactory = loggerFactory });

var client = Greeter.GreeterClient(channel);

Étendues du journal client gRPC

Le client gRPC ajoute une étendue de journalisation aux journaux consignés lors d’un appel gRPC. L’étendue a des métadonnées liées à l’appel gRPC :

• GrpcMethodType : type de méthode gRPC. Les valeurs possibles sont les noms de l’enum Grpc.Core.MethodType. Par exemple : Unary.
• GrpcUri : URI relatif de la méthode gRPC. Par exemple, /greet.Greeter/SayHellos.

Exemple de sortie de la journalisation

Voici un exemple de sortie de console au niveau Debug d’un client gRPC :

dbug: Grpc.Net.Client.Internal.GrpcCall[1]
      Starting gRPC call. Method type: 'Unary', URI: 'https://localhost:5001/Greet.Greeter/SayHello'.
dbug: Grpc.Net.Client.Internal.GrpcCall[6]
      Sending message.
dbug: Grpc.Net.Client.Internal.GrpcCall[1]
      Reading message.
dbug: Grpc.Net.Client.Internal.GrpcCall[4]
      Finished gRPC call.

Suivi

Les services gRPC et le client gRPC fournissent des informations sur les appels gRPC à l’aide de DiagnosticSource et Activity.

• gRPC .NET utilise une activité pour représenter un appel gRPC.
• Les événements de suivi sont écrits dans la source de diagnostic au début et à l’arrêt de l’activité d’appel gRPC.
• Le suivi ne capture pas d’informations sur le moment où les messages sont envoyés pendant la durée de vie des appels de diffusion en continu gRPC.

Suivi du service gRPC

Les services gRPC sont hébergés sur ASP.NET Core, qui signale les événements relatifs aux requêtes HTTP entrantes. Les métadonnées spécifiques à gRPC sont ajoutées aux diagnostics de requête HTTP existants qu’ASP.NET Core fournit.

• Le nom de la source de diagnostic est Microsoft.AspNetCore.
• Le nom de l’activité est Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • Le nom de la méthode gRPC appelée par l’appel gRPC est ajouté en tant que balise portant le nom grpc.method.
  • Le code d’état de l’appel gRPC lorsqu’il est terminé est ajouté en tant que balise portant le nom grpc.status_code.

Suivi du client gRPC

Le client gRPC .NET utilise HttpClient pour effectuer des appels gRPC. Bien que HttpClient écrive des événements de diagnostic, le client gRPC .NET fournit une source de diagnostic, une activité et des événements personnalisés afin que des informations complètes sur un appel gRPC puissent être collectées.

• Le nom de la source de diagnostic est Grpc.Net.Client.
• Le nom de l’activité est Grpc.Net.Client.GrpcOut.
  • Le nom de la méthode gRPC appelée par l’appel gRPC est ajouté en tant que balise portant le nom grpc.method.
  • Le code d’état de l’appel gRPC lorsqu’il est terminé est ajouté en tant que balise portant le nom grpc.status_code.

Collecte du suivi

Le moyen le plus simple d’utiliser DiagnosticSource consiste à configurer une bibliothèque de données de télémétrie comme Application Insights ou OpenTelemetry dans votre application. La bibliothèque traite les informations sur les appels gRPC en même temps que d’autres données de télémétrie d’application.

Le suivi peut être visualisé dans un service managé comme Application Insights, ou exécuté en tant que votre propre système de suivi distribué. OpenTelemetry prend en charge l’exportation des données de suivi vers Jaeger et Zipkin.

DiagnosticSource peut consommer des événements de suivi dans le code à l’aide de DiagnosticListener. Pour plus d’informations sur l’écoute d’une source de diagnostic avec du code, consultez le Guide de l’utilisateur DiagnosticSource.

Notes

Actuellement, les bibliothèques de télémétrie ne capturent pas les données de télémétrie Grpc.Net.Client.GrpcOut spécifiques à gRPC. Le travail d’amélioration des bibliothèques de télémétrie qui capturent ce traçage est en cours.

Mesures

Les métriques sont une représentation des mesures de données sur des intervalles de temps, par exemple, le nombre de requêtes par seconde. Les données de métriques permettent d’observer l’état d’une application à un niveau élevé. Les métriques gRPC .NET sont émises à l’aide de EventCounter.

Métriques de service gRPC

Les métriques de serveur gRPC sont signalées sur la source d’événement Grpc.AspNetCore.Server.

Nom	Description
total-calls	Nombre total d’appels
current-calls	Appels actuels
calls-failed	Total d’appels ayant échoué
calls-deadline-exceeded	Total d’appels dépassés
messages-sent	Nombre total de messages envoyés
messages-received	Total de messages reçus
calls-unimplemented	Nombre total d’appels non implémentés

ASP.NET Core fournit également ses propres métriques sur la source d’événement Microsoft.AspNetCore.Hosting.

Métriques du client gRPC

Les métriques du client gRPC sont signalées sur la source d’événement Grpc.Net.Client.

Nom	Description
total-calls	Nombre total d’appels
current-calls	Appels actuels
calls-failed	Total d’appels ayant échoué
calls-deadline-exceeded	Total d’appels dépassés
messages-sent	Nombre total de messages envoyés
messages-received	Total de messages reçus

Observer les métriques

dotnet-counters est un outil de surveillance des performances pour l’analyse ad hoc de l’intégrité et l’examen des performances de premier niveau. Surveillez une application .NET avec Grpc.AspNetCore.Server ou Grpc.Net.Client comme nom de fournisseur.

> dotnet-counters monitor --process-id 1902 Grpc.AspNetCore.Server

Press p to pause, r to resume, q to quit.
    Status: Running
[Grpc.AspNetCore.Server]
    Total Calls                                 300
    Current Calls                               5
    Total Calls Failed                          0
    Total Calls Deadline Exceeded               0
    Total Messages Sent                         295
    Total Messages Received                     300
    Total Calls Unimplemented                   0

Une autre façon d’observer les métriques gRPC consiste à capturer des données de compteur à l’aide du package Microsoft.ApplicationInsights.EventCounterCollector d’Application Insights. Une fois configuré, Application Insights collecte les compteurs .NET courants au moment de l’exécution. Les compteurs de gRPC ne sont pas collectés par défaut, mais App Insights peut être personnalisé pour inclure des compteurs supplémentaires.

Spécifiez les compteurs gRPC pour Application Insight à collecter dans Startup.cs :

    using Microsoft.ApplicationInsights.Extensibility.EventCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        //... other code...

        services.ConfigureTelemetryModule<EventCounterCollectionModule>(
            (module, o) =>
            {
                // Configure App Insights to collect gRPC counters gRPC services hosted in an ASP.NET Core app
                module.Counters.Add(new EventCounterCollectionRequest("Grpc.AspNetCore.Server", "current-calls"));
                module.Counters.Add(new EventCounterCollectionRequest("Grpc.AspNetCore.Server", "total-calls"));
                module.Counters.Add(new EventCounterCollectionRequest("Grpc.AspNetCore.Server", "calls-failed"));
            }
        );
    }

Ressources supplémentaires

• Journalisation dans .NET Core et ASP.NET Core
• Configuration de gRPC pour .NET
• Intégration de la fabrique de clients gRPC dans .NET