Log estruturado

Resumo

Logging estruturado registra dados como campos nomeados, não como texto concatenado. Isso permite buscar e filtrar por esses campos em ferramentas de observabilidade. Use templates com {Placeholder}, nunca interpolação.

1. Objetivos de Aprendizagem#

• Escrever logs estruturados com templates.
• Entender por que evitar interpolação de strings.
• Usar escopos (scopes) para agrupar contexto.

2. Pré-requisitos#

• ILogger e níveis (tópico 14.1).

3. Conceito#

Comparação:

• Ruim (interpolado): _logger.LogInformation($"Produto {id} criado"); — vira texto puro; o id não é um campo pesquisável.
• Bom (estruturado): _logger.LogInformation("Produto {ProdutoId} criado", id); — o provedor guarda ProdutoId como campo, permitindo consultas como "todos os logs de ProdutoId = 42".

O porquê: em produção, você não lê logs linha a linha — você consulta. Campos estruturados tornam isso possível. Scopes anexam contexto (ex.: RequestId) a um conjunto de logs.

4. Mão na Massa#

4.1. Setup#

dotnet new console -n Catalog.StructLog
cd Catalog.StructLog
dotnet add package Microsoft.Extensions.Hosting

4.2. Implementação Passo a Passo#

1. Template estruturado (a ordem dos argumentos casa com os placeholders):

logger.LogInformation("Pedido {PedidoId} criado com {Itens} itens", 7, 3);

2. Evite interpolação:

// EVITE — perde a estrutura:
// logger.LogInformation($"Pedido {pedidoId} criado");

3. Escopo para agrupar contexto:

using (logger.BeginScope("Requisição {RequestId}", Guid.NewGuid()))
{
    logger.LogInformation("Validando pedido");
    logger.LogInformation("Persistindo pedido");
    // ambos os logs carregam o RequestId do escopo
}

4.3. Executando#

dotnet run

5. Exemplo Completo#

LogInformation("Pedido {PedidoId} criado com {Itens} itens", 7, 3) gera uma mensagem legível e dois campos consultáveis (PedidoId, Itens) — o padrão para observabilidade real.

6. Boas Práticas e Armadilhas#

Atenção

a ordem dos argumentos deve corresponder à ordem dos placeholders no template — os nomes são rótulos, mas a associação é posicional.

7. Segurança e Produção#

• Nunca logue dados sensíveis/PII (senhas, tokens, CPF, cartões) — nem em campos estruturados. Logs costumam ir para sistemas externos e são retidos por muito tempo (impacto de LGPD).

8. Exercícios#

• Fácil: troque um log interpolado por um estruturado.
• Médio: adicione dois campos a uma mensagem e confirme a ordem dos argumentos.
• Desafio: use BeginScope para anexar um CorrelationId a um conjunto de logs.

9. Resumo#

Logging estruturado usa templates {Campo} para registrar dados pesquisáveis, nunca interpolação. Scopes anexam contexto. Jamais logue PII/segredos.

10. Próximos Passos#

A seguir, configurar provedores e níveis de logging.

11. Referências#

• Microsoft Learn — Logging estruturado
• Microsoft Learn — Escopos de log
• Microsoft Learn — Diretrizes de logging de alto desempenho