O registro, uma parte essencial do desenvolvimento de aplicativos, funciona como a caixa-preta de um avião. Sempre que algo dá errado, os registros são um ótimo lugar para começar a descobrir o que aconteceu e como consertar. Mas, apesar disso, muitos desenvolvedores tratam o registro como algo secundário, sem planejamento ou entendimento adequado antes da implementação.
O registro, especificamente o registro no .NET framework, precisa de mais atenção. Tanto desenvolvedores experientes quanto novatos em .NET devem ser capazes de identificar e corrigir os tipos de erros que podem surgir e prejudicar a qualidade de seus registros.
Como você pode investigar problemas em seu aplicativo sem as informações necessárias que um bom registro fornece? E como você pode entregar um software sólido sem corrigir nenhum erro ou consertar nenhum bug? Você precisa de boas práticas de registro.
A importância do registro em C#
O registro estruturado, que inclui bibliotecas .NET como Serilog, NLog ou a biblioteca padrão da Microsoft, torna a otimização do registro possível mesmo quando você está lidando com um alto volume. Para aplicativos nativos da nuvem, o padrão OpenTelemetry também pode ajudar a fornecer observabilidade completa em seu aplicativo. Mas essas ferramentas, por mais úteis que sejam, dependem da sua capacidade de evitar cometer erros durante o registro.
O registro incorreto ou incompleto dificulta a busca no seu backend. O registro correto, por outro lado, pode ajudar você a entender um bug específico na produção e encontrar os detalhes necessários para corrigir ou corrigir erros. Erros de registro são comuns, especialmente APIs baseadas em strings, e o método de copiar-colar-modificar de adicionar código de registro se presta a erros. Essas coisas podem resultar em problemas pequenos e negligenciados que se tornam problemas maiores no futuro, custando tempo e dinheiro às organizações.
Um bom registro ajuda os desenvolvedores a se moverem mais rápido e responderem de forma mais eficiente aos problemas que surgem. Por sua vez, isso torna a infraestrutura e o DevOps mais eficazes. Essa prática não deve ser despriorizada por desenvolvedores e organizações que desejam implantar software seguro, forte e de alta qualidade. Então, quais são alguns dos maiores e mais comuns erros que você pode cometer quando se trata de registro e como você pode corrigi-los ou evitá-los?
Sintaxe e Semântica da Mensagem
O C# requer uma mensagem correta com as informações certas no local certo. Mas como as APIs dependem de strings e argumentos não tipados, é fácil escorregar e cometer um erro. Aqui estão alguns dos erros mais comuns:
Sintaxe de mensagem incorreta
O registro estruturado em .NET precisa de uma sintaxe específica. Omitir colchetes específicos pode se transformar em erros não detectados e levar a saídas de log que não têm as informações de que você precisa. Espaços reservados incorretos também podem levar a erros — por exemplo, cada espaço reservado precisa de uma propriedade, que deve aderir à sintaxe padrão para identificadores na maioria dos idiomas, que deve começar com uma letra ou sublinhado e conter apenas letras, números ou sublinhados. Tenha cuidado com erros de digitação e certifique-se de fechar todos os seus colchetes corretamente.
Duplicação de placeholder
Todos os placeholders em uma mensagem de log devem ser únicos, vinculando-se ao objetivo de especificidade do log estruturado. Não repita nomes.
Ordem incorreta dos espaços reservados
A ordem dos espaços reservados deve corresponder à ordem dos argumentos, mas é fácil fazer uma troca acidental ao retrabalhar o código — e mais difícil de detectar depois.
Mensagens criadas manualmente
Antes do registro estruturado, as mensagens de registro eram frequentemente criadas com concatenação de strings. Agora, porém, backends de registro como o ILogger usam a abordagem estruturada, que ajuda com consultas e facilita armazenamento e indexação mais eficientes. Graças a essas soluções, você não precisa mais criá-las manualmente.
Usando a sobrecarga errada
A maioria dos frameworks de registro em C# têm sobrecargas específicas que permitem passar um nível de registro, ID de evento ou exceção. Passar valores de sobrecarga pode fazer com que seu código faça algo não intencional. Certifique-se de usar sobrecargas adequadas para obter melhores resultados.
Categoria de logger errada
O sabor genérico do ILogger indica o tipo para o qual o logger é. A saída do log mostra qual classe gerou uma entrada de log específica emitindo o nome do tipo que você passou. É um recurso útil, mas pode levar a erros na configuração, então tenha cuidado ao empregá-lo. Copiar e colar pode ser responsável por esses tipos de erros, levando a uma interpretação errada dos logs e perda de tempo no diagnóstico de problemas.
Exceção não registrada
Quando se trata de exceções, os logs emitidos devem conter a exceção. Você quer incluir todos os detalhes de uma exceção para que seja mais fácil encontrar um problema se e quando chegar a hora.
Convenções e Consistência
O registro existe em todas as suas bases de código, o que significa que você precisa definir convenções para manter tudo consistente e ajudar a evitar sobrecarga de informações. Convenções adequadas podem ajudar você a "ignorar" detalhes irrelevantes e se concentrar em um problema central; elas também ajudam durante modificações de código, garantindo que os objetos estejam onde você espera que estejam. Tanto equipes quanto indivíduos se beneficiam dessa prática. Aqui estão algumas coisas para manter em mente com convenções:
Nomenclatura consistente de espaços reservados
Embora seja importante usar espaços reservados diferentes, eles ainda devem seguir uma convenção de nomenclatura consistente, assim como as variáveis, para maior facilidade de uso.
Campos de armazenamento do logger
Criar uma política para nomear o campo de armazenamento do seu logger ajudará você a encontrá-lo mais facilmente — ele permanece consistente em toda a base de código. Em projetos com uma infinidade de loggers injetados, você deve sempre usar o mesmo nome de campo.
Considerações sobre desempenho e arquivo de log
Ainda há algumas outras coisas para pensar ao registrar. Prestar atenção a essas considerações ajudará a manter seus registros em um bom lugar:
Métodos Trace.Write...
Embora agora tenhamos ILogger e outras opções para registro estruturado, é importante lembrar que nossas escolhas costumavam ser limitadas. Bases de código legadas podem usar as classes Trace e TraceSwitch, o que significa que elas exigem um tipo diferente de atenção. Os desenvolvedores devem evitar a família de métodos Trace.Write... especificamente e ficar com TraceInformation, TraceWarning ou TraceError quando necessário.
Overlogging
Você pode ter muito de uma coisa boa. Overlogging pode levar à degradação do desempenho, sobrecarga de arquivo de log e código difícil de ler ou entender. Seja estratégico com seus logs. Você também pode registrar muitas exceções. Evite registrar e relançar uma exceção e, em vez disso, atenha-se a uma para que seus arquivos sejam mais fáceis de usar.
E agora?
O código de log envolve várias partes móveis diferentes e considerações importantes para que você possa evitar cometer erros caros e demorados. No entanto, cobrimos apenas algumas coisas para saber enquanto você executa a prática.
Logs sólidos, no entanto, ajudam a garantir uma mitigação mais fácil de problemas e correção de bugs ao longo do caminho para que você esteja entregando software de forma rápida e perfeita. Ler sobre OpenTelemetry pode ajudar com o código de log — e o Sonar também. Mantendo as peculiaridades do log do C# em mente, você pode garantir que o código limpo que você escreve leva ao tipo de software de alta qualidade que sua organização precisa.
