Editar

Compartilhar via

Registros em log no Gridwich

Azure

As melhores práticas para registrar em log incluem:

  • Não use formatação nem interpolação de cadeia de caracteres. O registro em log de uma cadeia de caracteres com $"This broke {brokenThing}" não é útil para depuração.

  • Passe objetos para que eles 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 de trabalho significativo, use o seguinte padrão de registro em log:

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

  • Embora você possa registrar qualquer informação em qualquer fase, não polua os logs com elementos estranhos.

ObjectLogger

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

O ObjectLogger/IObjectLogger restringe o uso de métodos de agente 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 usarem EventIds, que são úteis para depuração.

Outras recomendações para usar ObjectLogger incluem:

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

Esquema e dados de log

A infraestrutura de runtime da Grade de Eventos subjacente 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 complexas e fluxos de trabalho que exigem várias entradas e saídas, você pode criar um objeto de contexto, que é um recipiente de propriedades de variáveis importantes que o código pode passar ou gerar. 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 agente 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 suar o seguinte código:

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 log

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

LogLevel Enumeração Descrição
LogTrace 0 Contém as mensagens mais detalhadas e podem 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 1 Usado para investigação interativa durante o desenvolvimento. Esses logs devem conter principalmente informações úteis para depuração e não têm valor de longo prazo.
LogInformation 2 Rastreia o fluxo geral do aplicativo. Esses logs devem ter valor de longo prazo.
LogWarning 3 Realça um evento anormal ou inesperado no fluxo do aplicativo, mas não interrompe a execução do aplicativo.
LogError 4 Registra quando o fluxo de execução atual é interrompido devido a uma falha. Esses logs devem indicar falhas na atividade atual, e não em todo o aplicativo.
LogCritical 5 Descreve uma falha irrecuperável do aplicativo ou do sistema ou uma falha catastrófica que exige atenção imediata.
LogNone 6 Não são usados para gravar mensagens de log. Especifica que uma categoria de log não deve gravar mensagens.

Próximas etapas

Documentação do produto:

Módulos do Microsoft Learn: