Usando um registrador para adicionar mensagens de log personalizadas

  • 5 minutos

O .NET fornece APIs que você pode usar para registrar dados de telemetria personalizados. O OpenTelemetry pode exportar esses dados.

Nesta unidade, você aprenderá a escrever código eficiente que envia eventos para logs estruturados.

Objetos ILogger

As ferramentas do .NET Aspire configuram a API OpenTelemetry automaticamente quando você cria um projeto com base nos modelos ou adiciona um projeto existente à orquestração do .NET Aspire . Quando você deseja gravar telemetria, não precisa criar seus próprios objetos de registro, métricas ou rastreamento. Em vez disso, você pode recuperá-los usando a injeção de dependência em seus microsserviços.

Por exemplo, na classe BasketService a seguir, um objeto ILogger é incluído na declaração de classe. Você pode usar esse logger em qualquer lugar da classe para escrever eventos:

public class BasketService(
    IBasketRepository repository,
    ILogger<BasketService> logger) : Basket.BasketBase
{
    [AllowAnonymous]
    public override async Task<CustomerBasketResponse> GetBasket(
        GetBasketRequest request, ServerCallContext context)
    {
        var userId = context.GetUserIdentity();

        // Use the logger to write events
        if (logger.IsEnabled(LogLevel.Debug))
        {
            logger.LogDebug("Begin GetBasketById call from method {Method} for basket id {userId}", context.Method, userId);
        }

        var data = await repository.GetBasketAsync(userId);

        return new();
    }
}

Registo eficiente

O registro em log ajuda a tornar seu microsserviço observável. Quando o aplicativo é testado, preparado e implantado na produção, um código de log completo pode permitir o diagnóstico rápido de falhas ou gargalos. Portanto, é tentador registrar tudo. No entanto, embora o registro seja rápido, ele não tem custo zero, e você deve ter cuidado para registrar de forma eficiente.

Os fornecedores geralmente faturam sistemas de gerenciamento de desempenho de aplicativos (APMs) com base no volume de dados que ingerem. Selecionar o nível de log apropriado para suas mensagens e os níveis de coleta padrão pode ter um grande efeito na fatura mensal. Os níveis de coleta de log podem ser definidos por provedor, que normalmente é o nome do tipo usado em ILogger<T>.

Utilize as seguintes técnicas sempre que iniciar sessão:

  • Verifique se o nível de log que você deseja usar está habilitado. Os níveis disponíveis incluem informações, aviso, erro e crítica. Os administradores podem habilitar diferentes níveis ao testar, preparar e implantar na produção. A saída de log é controlada por meio de IConfiguration, normalmente usando variáveis de ambiente ou appsettings.json.
  • Evite a interpolação de sequência de caracteres na mensagem registada. As cadeias de caracteres interpoladas são definidas com o símbolo $ e são avaliadas mesmo que o nível de log escolhido não esteja habilitado. Em vez disso, use um método de log como LogInformation() ou LogDebug() e passe parâmetros na lista de argumentos.
  • Use a geração de código de origem em tempo de compilação para otimizar ainda mais o desempenho do registo e criar um identificador exclusivo para cada mensagem de registo, o que é útil ao consultar mensagens de registo num APM.

Geração de código-fonte em tempo de compilação

A geração de código em tempo de compilação com objetos ILogger reduz o custo do log ao realizar a análise de string uma vez, em vez de em cada solicitação de log. Ele também inclui um ID para cada tipo de mensagem de log. Para usar essa técnica, defina métodos de log parciais com os parâmetros de log e aplique o LoggerMessageAttribute a eles. O .NET gera automaticamente o método de log completo quando o código é compilado.

Lembre-se de que, no .NET Aspire, você não precisa criar um ILogger, mas pode obtê-lo a partir da injeção de dependência:

public partial class BasketService(
    IBasketRepository repository,
    ILogger<BasketService> logger) : Basket.BasketBase
{
    [LoggerMessage(
        EventId = 0,
        Level = LogLevel.Information,
        Message = "Obtaining a basket from method {Method} for basket {basketId}")]
    public partial void LogGetBasket(string Method, int basketId);
}

Saiba mais