Ведение журнала и диагностика в gRPC на платформе .NET

Автор: Джеймс Ньютон-Кинг (James Newton-King)

В этой статье приводятся рекомендации по сбору диагностических данных из приложения gRPC с целью устранения неполадок. В книге рассматриваются такие темы:

• Ведение журналов — структурированные журналы, записываемые в систему ведения журналов .NET Core. Интерфейс ILogger используется платформами приложений для записи журналов, а пользователями — для ведения собственных журналов в приложении.
• Трассировка — события, которые связаны с операцией, записанной с помощью DiaganosticSource и Activity. Трассировки из источника диагностических данных обычно используются для сбора данных телеметрии приложений такими библиотеками, как Application Insights и OpenTelemetry.
• Метрики — представление мер данных за интервалы времени, например количество запросов в секунду. Метрики создаются с помощью EventCounter и могут отслеживаться с помощью программы командной строки dotnet-counters или Application Insights.

Ведение журналов

Службы gRPC и клиент gRPC записывают журналы с помощью системы ведения журналов .NET Core. Для отладки непредвиденного поведения в службах и клиентских приложениях рекомендуется начать с журналов.

Ведение журналов служб gRPC

Предупреждение

Журналы на стороне сервера могут содержать конфиденциальные сведения из приложения. Никогда не публикуйте необработанные журналы из рабочих приложений на общедоступных форумах, таких как GitHub.

Так как службы gRPC размещаются на платформе ASP.NET Core, они используют систему ведения журналов ASP.NET Core. В конфигурации по умолчанию gRPC записывает минимальное количество сведений, но это можно настроить. Подробные сведения о настройке ведения журналов в ASP.NET Core см. в документации по ведению журналов в ASP.NET Core.

gRPC добавляет журналы в категорию Grpc. Чтобы включить подробные журналы от gRPC, настройте префиксы Grpc с уровнем Debug в файле appsettings.json, добавив следующие элементы в подраздел LogLevel раздела Logging:

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

Ведение журнала также можно настроить в файле Program.cs с помощью ConfigureLogging:

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

Если вы не используете конфигурацию на основе JSON, задайте следующее значение конфигурации в системе конфигурации:

• Logging:LogLevel:Grpc = Debug

Сведения о задании вложенных значений конфигурации см. в документации по своей системе конфигурации. Так, при использовании переменных среды вместо символа : применяются два символа _ (например, Logging__LogLevel__Grpc).

При сборе подробных диагностических данных для приложения мы рекомендуем использовать уровень Debug. На уровне Trace создаются подробные диагностические данные, которые редко требуются для диагностики проблем.

Пример выходных данных ведения журнала

Вот пример выходных данных консоли для службы gRPC на уровне Debug:

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

Доступ к журналам на стороне сервера

Доступ к журналам на стороне сервера зависит от среды приложения.

Консольное приложение

В консольном приложении по умолчанию должно быть включено средство ведения журнала консоли. Журналы gRPC будут выводиться в консоли.

Другие среды

Если приложение развернуто в другой среде (например, Docker, Kubernetes или службе Windows), обратитесь к статье Ведение журнала в .NET Core и ASP.NET Core за дополнительными сведениями о настройке подходящих поставщиков ведения журнала.

Ведение журналов клиента gRPC

Предупреждение

Журналы на стороне клиента могут содержать конфиденциальные сведения из приложения. Никогда не публикуйте необработанные журналы из рабочих приложений на общедоступных форумах, таких как GitHub.

Чтобы получать журналы из клиента .NET, можно задать свойство GrpcChannelOptions.LoggerFactory при создании канала клиента. Если служба gRPC вызывается из приложения ASP.NET Core, производство средства ведения журнала может разрешаться посредством внедрения зависимостей:

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

Другой способ включить ведение журналов клиента — использовать производство клиента gRPC для создания клиента. Клиент gRPC, зарегистрированный в производстве клиента и разрешенный посредством внедрения зависимостей, будет автоматически использовать настроенные для приложения параметры ведения журналов.

Если приложение не использует внедрение зависимостей, вы можете создать экземпляр ILoggerFactory с помощью метода LoggerFactory.Create. Для доступа к этому методу добавьте в приложение пакет Microsoft.Extensions.Logging.

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

Области журналов клиента gRPC

Клиент gRPC добавляет область ведения журналов для журналов, создаваемых во время вызова gRPC. Область включает в себя метаданные, связанные с вызовом gRPC.

• GrpcMethodType — тип метода gRPC. Возможными значениями являются имена из перечисления Grpc.Core.MethodType. Например, Unary.
• GrpcUri — относительный универсальный код ресурса (URI) метода gRPC. Например, /greet.Greeter/SayHellos.

Пример выходных данных ведения журнала

Вот пример выходных данных консоли для клиента gRPC на уровне Debug:

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.

Трассировка

Службы gRPC и клиент gRPC предоставляют сведения о вызовах gRPC с помощью DiagnosticSource и Activity.

• .NET gRPC использует действие для представления вызова gRPC.
• События трассировки записываются в источник диагностических данных в начале и конце действия вызова gRPC.
• При трассировке не собираются сведения о том, когда в течение времени существования вызовов потоковой передачи gRPC отправляются сообщения.

Трассировка службы gRPC

Службы gRPC размещаются на платформе ASP.NET Core, которая сообщает события, связанные с входящими HTTP-запросами. К существующим данным диагностики HTTP-запросов, которые предоставляет платформа ASP.NET Core, добавляются метаданные, связанные с gRPC.

• Имя источника диагностических данных — Microsoft.AspNetCore.
• Имя действия — Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • Имя метода gRPC в вызове gRPC добавляется в качестве тега с именем grpc.method.
  • Код состояния вызова gRPC после его завершения добавляется в качестве тега с именем grpc.status_code.

Трассировка клиента gRPC

Клиент .NET gRPC использует HttpClient для выполнения вызовов gRPC. Хотя HttpClient записывает события диагностики, клиент .NET gRPC предоставляет пользовательский источник диагностических данных, действия и события для сбора полных сведений о вызове gRPC.

• Имя источника диагностических данных — Grpc.Net.Client.
• Имя действия — Grpc.Net.Client.GrpcOut.
  • Имя метода gRPC в вызове gRPC добавляется в качестве тега с именем grpc.method.
  • Код состояния вызова gRPC после его завершения добавляется в качестве тега с именем grpc.status_code.

Сбор трассировки

Самый простой способ использовать DiagnosticSource — настроить в приложении библиотеку телеметрии, например Application Insights или OpenTelemetry. Библиотека будет обрабатывать сведения о вызовах gRPC вместе с другими данными телеметрии приложения.

Результаты трассировки можно просматривать в управляемой службе, например Application Insights, либо же можно использовать собственную распределенную систему трассировки. OpenTelemetry поддерживает экспорт данных трассировки в Jaeger и Zipkin.

DiagnosticSource может использовать события трассировки в коде с помощью DiagnosticListener. Сведения о прослушивании источника диагностических данных в коде см. в руководстве пользователя DiagnosticSource.

Примечание.

В настоящее время библиотеки телеметрии не собирают данные телеметрии Grpc.Net.Client.GrpcOut, относящиеся к gRPC. Работа над реализацией сбора этих данных трассировки библиотеками телеметрии ведется.

Метрики

Метрики — это представление мер данных за интервалы времени, например количество запросов в секунду. Метрики позволяют отслеживать общее состояние приложения. Метрики .NET gRPC создаются с помощью EventCounter.

Метрики службы gRPC

Метрики сервера gRPC формируются в источнике событий Grpc.AspNetCore.Server.

Имя	Описание
total-calls	Всего звонков
current-calls	Текущие вызовы
calls-failed	Всего вызовов с ошибками
calls-deadline-exceeded	Всего вызовов с истекшим сроком
messages-sent	Всего отправленных сообщений
messages-received	Всего полученных сообщений
calls-unimplemented	Всего нереализованных вызовов

ASP.NET Core также предоставляет собственные метрики в источнике событий Microsoft.AspNetCore.Hosting.

Метрики клиента gRPC

Метрики клиента gRPC формируются в источнике событий Grpc.Net.Client.

Имя	Описание
total-calls	Всего звонков
current-calls	Текущие вызовы
calls-failed	Всего вызовов с ошибками
calls-deadline-exceeded	Всего вызовов с истекшим сроком
messages-sent	Всего отправленных сообщений
messages-received	Всего полученных сообщений

Отслеживание метрик

dotnet-counters — это средство мониторинга производительности и первого уровня анализа производительности. Для отслеживания приложения .NET используйте имя поставщика Grpc.AspNetCore.Server или Grpc.Net.Client.

> 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

Еще один способ отслеживания метрик gRPC заключается в сборе данных счетчиков с помощью пакета Microsoft.ApplicationInsights.EventCounterCollector Application Insights. После настройки Application Insights собирает показания стандартных счетчиков .NET во время выполнения. Показания счетчиков gRPC по умолчанию не собираются, но в Application Insights можно включить дополнительные счетчики.

Укажите счетчики gRPC для Application Insights для сбора данных: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"));
            }
        );
    }

Дополнительные ресурсы

• Ведение журнала в .NET Core и ASP.NET Core
• gRPC для конфигурации .NET
• Интеграция клиентской фабрики gRPC в .NET