Editar

Partilhar via

Iniciar sessão em Gridwich

Azure

As práticas recomendadas para registro em log incluem:

  • Não use formatação de cadeia de caracteres ou interpolação. Registrar uma cadeia de caracteres com $"This broke {brokenThing}" não é útil para depuração.

  • Passe objetos para que se tornem campos pesquisáveis.

    Em vez de LogInformation(LogEventIds.StartProcessing, $"Processing has started on item {Item.itemNumber}");, use:

    • Um objeto como tal, como LogInformationObject(LogEventIds.StartProcessing, Item);, ou
    • Objetos anônimos, como LogInformationObject(LogEventIds.StartProcessing, new {Item.itemNumber, Item.itemDescription, someData});.

  • Siga as convenções de numeração EventId descritas em LogEventIds.

  • Para qualquer corpo significativo de trabalho, use o seguinte padrão de registro:

    • Use LogInformationObject na entrada, por exemplo, quando estiver prestes a iniciar um trabalho de codificação.
    • Use LogInformationObject no sucesso, por exemplo, quando o trabalho de codificação for bem-sucedido.
    • Use LogWarningObject, ou LogCriticalObject em caso de falha, por exemplo, LogErrorObjectse o trabalho de codificação falhar. Use variantes do método Exception, se aplicável.

  • Embora você possa registrar qualquer informação em qualquer estágio, não polua os logs com ruídos estranhos.

ObjectLogger

ObjectLogger com IObjectLogger é um pequeno utilitário wrapper para o Logger/ILogger padrão. Este utilitário de linha única registra qualquer objeto C# convertendo objetos C# em objetos de dicionário que o registrador pode consumir.

ObjectLogger/IObjectLogger restringe o uso de métodos de logger que não têm EventIds usando um padrão de adaptador, em vez de herança. Essa restrição força os desenvolvedores a usar EventIds, que são úteis para depuração.

Outras recomendações para usar o ObjectLogger incluem:

  • Não ignore IObjectLogger usando ILogger.
  • Use IObjectLogger com o tipo adequado para sua classe: IObjectLogger<myClass>.
  • Em qualquer bloco catch de manipulação de exceção, use os métodos IObjectLogger que incluem exceções. Provedores de registro em log, como o Application Insights, podem usar as informações de exceção.

Esquema e dados de registro em log

A infraestrutura de tempo de execução subjacente da Grade de Eventos fornece um esquema base. O esquema de eventos da Grade de Eventos inclui a hora do evento, o dispositivo de origem, o nível de gravidade e a mensagem de cadeia de caracteres. As propriedades personalizadas padrão do Logger/ILogger incluem EventId, Categorye RequestPath.

Objetos de contexto

Para trabalhar com APIs e fluxos de trabalho complexos que exigem várias entradas e saídas, você pode criar um objeto de contexto, que é um conjunto de propriedades de variáveis importantes que seu código pode passar ou gerar. Os objetos de contexto podem lidar com muitos parâmetros, e as assinaturas de método não precisam ser alteradas quando você adiciona ou remove parâmetros. Você também pode passar objetos de contexto para o registrador e outras interfaces como uma unidade.

Por exemplo, em vez de:

var store = new StorageBlob();
var tier = req.Query["tier"];
var result = await store.SetBlobStorageTier(blobName, tier);
logger.LogInformationObject(LogEventIds.setBlobProperties, result);

Você pode codificar:

var storageContext = new StorageContext();
storageContext.Store = new StorageBlob();
storageContext.Tier = req.Query["tier"];
storageContext.Result = await store.SetBlobStorageTier(blobName, storageContext.Tier);
logger.LogInformationObject(LogEventIds.setBlobProperties, storageContext);

Níveis de registo

Atribuir o nível de log apropriado pode não ser simples. As descrições gerais a seguir dos níveis de log são do LogLevel Enum.

LogLevel Enum Descrição
LogTrace 0 Contém as mensagens mais detalhadas e pode conter dados confidenciais do aplicativo. Essas mensagens são desativadas por padrão e não devem ser ativadas em um ambiente de produção.
LogDebug 5 Usado para investigação interativa durante o desenvolvimento. Esses logs contêm principalmente informações que são úteis para depuração e não têm valor a longo prazo.
LogInformation 2 Rastreia o fluxo geral do aplicativo. Esses logs devem ter valor a longo prazo.
LogWarning 3 Destaca um evento anormal ou inesperado no fluxo do aplicativo, mas não interrompe a execução do aplicativo.
LogError 4 Registra quando o fluxo atual de execução é interrompido devido a uma falha. Esses logs devem indicar falhas na atividade atual, não uma falha em todo o aplicativo.
LogCritical 5 Descreve uma falha irrecuperável do aplicativo ou do sistema, ou uma falha catastrófica que requer atenção imediata.
LogNenhum 6 Não é usado para escrever mensagens de log. Especifica que uma categoria de registro em log não deve gravar mensagens.

Próximos passos

Documentação do produto:

Módulos do Microsoft Learn: