Pular para o conteúdo principal

Logs - Rest PKI Core

O Rest PKI Core pode gravar logs nos seguintes destinos:

O destino padrão depende da plataforma usada.

PlataformaDestino padrão dos logs
LinuxSaída padrão, que é registrada automaticamente no log do sistema (já que a aplicação é executada como daemon)
DockerSaída padrão, o que em geral significa que os logs acabam nos logs do orquestrador
AzureAzure Table

Níveis​

Os logs são classificados em um de 6 níveis de severidade:

LogLevelDescrição
TraceContém as mensagens mais detalhadas. Essas mensagens podem conter dados sensíveis da aplicação. Ficam desabilitadas por padrão e não devem ser habilitadas em produção.
DebugPara depuração e desenvolvimento. Use com cautela em produção, por causa do grande volume.
InformationAcompanha o fluxo geral da aplicação. Pode ter valor a longo prazo.
WarningPara eventos anormais ou inesperados. Em geral, inclui erros ou condições que não fazem a aplicação falhar.
ErrorPara erros e exceções que não podem ser tratados. Essas mensagens indicam uma falha na operação ou requisição atual, não uma falha de toda a aplicação.
CriticalPara falhas que exigem atenção imediata. Exemplos: cenários de perda de dados, falta de espaço em disco.

Por padrão, são registrados os logs com severidade Warning ou superior.

Isso pode ser alterado, por exemplo, para habilitar os logs com severidade Information ou superior:

[Logging:LogLevel]
Default=Information

Ou, com variáveis de ambiente:

Logging__LogLevel__Default=Information

Categorias​

Os logs também são classificados em categorias, que podem ser usadas para habilitar logs com uma severidade mínima diferente conforme a categoria. Por exemplo, para habilitar logs com severidade Debug ou superior apenas das categorias que começam com o prefixo Lacuna.RestPki (a relevância desse prefixo é explicada abaixo):

[Logging:LogLevel]
Lacuna.RestPki=Debug

Ou, com variáveis de ambiente:

Logging__LogLevel__Lacuna.RestPki=Debug

Abaixo estão alguns prefixos de categoria úteis.

Prefixo da categoriaDescrição
Lacuna.RestPkiLogs gerados pela própria aplicação (e não por bibliotecas ou dependências externas)
Microsoft.EntityFrameworkCoreTodas as mensagens do Entity Framework Core (framework de acesso a dados usado pela aplicação)
Microsoft.EntityFrameworkCore.DatabaseTodas as interações com o banco de dados
Microsoft.AspNetCore.Hosting.DiagnosticsRequisições e respostas HTTP

Habilitando o registro de dados sensíveis​

Por padrão, dados sensíveis, como o conteúdo das requisições HTTP ou os parâmetros dos comandos SQL, não são registrados no log, independentemente do nível mínimo de severidade configurado. Para habilitar o registro de dados sensíveis:

[General]
EnableSensitiveDataLogging=True

Ou, com variáveis de ambiente:

General__EnableSensitiveDataLogging=True

Formatação JSON / logs estruturados​

O Rest PKI Core gera logs estruturados. No entanto, por padrão, os logs são gravados na saída padrão em um formato legível por humanos, que "achata" as informações em uma única string, perdendo a estrutura que, de outra forma, estaria disponível.

Para evitar essa perda de dados, habilite a formatação JSON nos logs gravados na saída padrão:

[Logging:Console]
FormatterName=json

Ou, com variáveis de ambiente:

Logging__Console__FormatterName=json

Gravando logs em arquivo​

Para gravar os logs em um arquivo, configure a aplicação da seguinte forma:

[Serilog:WriteTo:0]
Name=File

[Serilog:WriteTo:0:Args]
path=PATH_TO_LOG_FILE
outputTemplate={Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] [{SourceContext}] {Message:lj}{NewLine}{Exception}

Ou, com variáveis de ambiente:

Serilog__WriteTo__0__Name=File
Serilog__WriteTo__0__Args__path=PATH_TO_LOG_FILE
Serilog__WriteTo__0__Args__outputTemplate={Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] [{SourceContext}] {Message:lj}{NewLine}{Exception}

Para mais informações sobre a configuração outputTemplate, consulte Formatting Output.

Observe que, ao gravar logs em arquivo, a configuração do nível mínimo de severidade é diferente:

[Serilog:MinimumLevel]
Default=Error

[Serilog:MinimumLevel:Override]
Lacuna.RestPki=Information
Microsoft.EntityFrameworkCore.Database=Debug
Serilog__MinimumLevel__Default=Error
Serilog__MinimumLevel__Override__Lacuna.RestPki=Information
Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore.Database=Debug

Além disso, nessa sintaxe de configuração os níveis Trace e Critical se chamam, respectivamente, Verbose e Fatal.

Registrando requisições e respostas HTTP no log​

Para habilitar o registro de requisições e respostas HTTP no log:

[HttpLogging]
Enabled=True

Ou, com variáveis de ambiente:

HttpLogging__Enabled=True

OBSERVAÇÃO: Para que o log funcione, é necessário configurar o nível de log da categoria Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware como Information

Feito isso, as requisições já serão registradas com uma configuração padrão. Se quiser mais controle sobre essas configurações, estão disponíveis as seguintes opções:

OpçãoTipoDescrição
EnabledboolDefina como true para habilitar o log HTTP; caso contrário, defina como false.
LoggingFieldsstringEspecifica os campos da requisição e da resposta a serem registrados. Por padrão, registra as propriedades e os headers da requisição e da resposta. Os valores suportados estão listados aqui. Obs.: substitui o LoggingFields padrão.
AdditionalLoggingFieldsstringCampos adicionais a serem incluídos no log.
RequestHeadersstringEspecifica os headers de requisição HTTP que podem ser registrados. Um header não permitido é registrado com o valor [Redacted]. Obs.: substitui os headers de requisição padrão.
AdditionalRequestHeadersstringHeaders de requisição HTTP adicionais a serem incluídos no log.
ResponseHeadersstringEspecifica os headers de resposta HTTP que podem ser registrados. Um header não permitido é registrado com o valor [Redacted]. Obs.: substitui os headers de resposta padrão.
AdditionalResponseHeadersstringHeaders de resposta HTTP adicionais a serem incluídos no log.
MediaTypeOptionsstringConfigura as codificações de um tipo de mídia específico. Obs.: substitui as opções de tipo de mídia padrão.
AdditionalMediaTypeOptionsstringOpções de tipo de mídia adicionais.
RequestBodyLogLimitintLimita o tamanho máximo do corpo da requisição a ser registrado (em bytes). Padrão: 32 KB.
ResponseBodyLogLimitintLimita o tamanho máximo do corpo da resposta a ser registrado (em bytes). Padrão: 32 KB.

Exemplos​

Por padrão, o corpo da requisição não é registrado. Para habilitá-lo, use um dos seguintes métodos:

[HttpLogging]
LoggingFields=RequestBody           # Override default logging fields
AdditionalLoggingFields=RequestBody # RequestBody will be appended to default logging fields

Ou, com variáveis de ambiente:

HttpLogging__LoggingFields=RequestBody
HttpLogging__AdditionalLoggingFields=RequestBody

Headers não permitidos aparecem com o valor [Redacted]. Para exibir o valor dos headers de que você precisa, use:

[HttpLogging]
AdditionalRequestHeaders=cookie,Sec-Fetch-Dest

Ou, com variáveis de ambiente:

HttpLogging__AdditionalRequestHeaders=cookie,Sec-Fetch-Dest

Se quiser limitar o tamanho do corpo da requisição registrado no log:

[HttpLogging]
RequestBodyLogLimit=5120 # limit to 5KB (5 * 1024) = 5120

Ou, com variáveis de ambiente:

HttpLogging__RequestBodyLogLimit=5120
Ver em Markdown