Revisão de logs

Este capítulo reúne o conteúdo de logs para revisão: os erros mais comuns, os checklists de atendimento, o glossário, as referências e perguntas que misturam vários assuntos.

Erros comuns

• Ler só a mensagem final. As etapas anteriores da mesma operação podem explicar o encadeamento, e a primeira anomalia encontrada é um ponto de investigação, e não uma causa automática.
• Ignorar a data, o fuso e os relógios. O Z indica o UTC, a conversão para o -03:00 subtrai três horas e pode mudar o dia, e os relógios diferentes alteram a ordem aparente.
• Ordenar pelo horário errado. Um coletor pode mostrar o momento do recebimento, e não o do evento na origem, e a conversão do fuso não corrige um relógio adiantado.
• Concluir que não há registro sem conferir o período. A rotação pode deixar o evento em um arquivo anterior ou dividir a operação entre dois arquivos.
• Editar o arquivo ativo ou a única cópia coletada. O material fica preservado, e as transformações acontecem em uma cópia de trabalho.
• Acompanhar uma ocorrência nova em uma cópia estática. A cópia não recebe as linhas novas, e o acompanhamento usa o arquivo que continua sendo gravado.
• Tratar a ausência de uma linha como prova da ausência do evento. O programa pode não registrar a etapa, o trecho pode estar incompleto, e a mensagem pode estar em outro arquivo.
• Concluir o resultado só pelo Enviado, pelo Recebido ou pelo HTTP 200. Os marcadores dependem do programa, e o resultado técnico e o conteúdo da resposta são lidos conforme o contrato.
• Ligar o pedido e a resposta pela proximidade das linhas. As tarefas simultâneas intercalam os registros, e a operação e a tentativa ligam a conversa.
• Formatar a mensagem com o prefixo do log ou sobre o original. O formatador recebe só o conteúdo, em uma cópia, e o original continua sendo a evidência.
• Remover à mão as barras de um JSON escapado. O texto interno é interpretado em uma segunda etapa, e a remoção manual pode alterar o valor.
• Extrair só as linhas que contêm um termo. O filtro pode descartar o resto de um registro de várias linhas ou uma etapa necessária ao contexto.
• Confundir linhas de erro com operações afetadas. Uma tentativa pode produzir vários registros, e uma operação pode ter várias tentativas.
• Remover duplicadas sem normalizar. Os campos variáveis são normalizados em uma cópia separada, com os códigos e as condições que distinguem os tipos de erro preservados.
• Repetir uma operação sem confirmar a tentativa anterior. O fornecedor ou o banco pode ter processado algo cujo resultado não chegou ao cliente.
• Tratar os erros 1205 e 1213 da mesma forma. O 1205 desfaz, por padrão, só o comando que esperava, e o 1213 desfaz a transação escolhida como vítima.
• Comparar o log do MySQL com o Windows sem conferir o fuso. O MySQL 5.1 grava a hora local sem o fuso, e, a partir do 5.7, o padrão das mensagens é o UTC.
• Atribuir uma causa física pelo ping. O ping observa o ICMP em sondagens, e a falha ou a resposta dele não aponta, sozinha, o cabo nem a estabilidade da aplicação.
• Contar as perdas do ping só pelo texto Esgotado. As outras mensagens de falha ficam de fora, e os títulos e as estatísticas não são tentativas.
• Tratar o ID 41 como prova de falta de energia. O evento é gravado na inicialização seguinte e registra só o encerramento incorreto.
• Filtrar os eventos só pelo nível Crítico. A parada de um serviço ou o início de uma manutenção podem estar em outros níveis.
• Compartilhar o log sem preparar o trecho. As senhas, os tokens e os dados sensíveis são mascarados na versão compartilhada, com o contexto necessário mantido.

Checklist antes de abrir o log

• O relato identifica a operação, a data, o horário, o fuso, a máquina e um código útil para a busca?
• A origem inicial corresponde à pergunta do atendimento?
• Os arquivos disponíveis cobrem o período, inclusive os de rotação?
• A origem e o momento da coleta estão anotados, com uma cópia preservada?
• O início, o fim, os filtros e as lacunas da coleta estão declarados?

Checklist da leitura de uma operação

• A mesma operação e a mesma tentativa foram acompanhadas, sem ligar linhas só pela proximidade?
• A primeira anomalia disponível e o contexto anterior e posterior foram lidos?
• Os registros de várias linhas foram preservados completos?
• Os fusos e as possíveis diferenças entre os relógios foram considerados?
• O campo usado na linha do tempo é o horário do evento ou o da coleta?

Checklist de uma integração

• O significado do Enviado e do Recebido naquele programa está conhecido?
• O resultado técnico e o resultado de negócio foram lidos conforme o contrato?
• A mensagem formatada veio de uma cópia, sem o prefixo do log, com o original preservado?
• Uma operação de resultado desconhecido teve a situação consultada antes de qualquer repetição?
• O trecho para o fornecedor traz os identificadores e as tentativas, com os dados sensíveis mascarados?

Checklist das contagens e das comparações

• A expressão regular foi testada em ocorrências conhecidas?
• A frequência tem o período, os terminais e a unidade de contagem definidos?
• A normalização preservou os códigos de erro e a ligação com as linhas originais?
• A comparação usou uma operação parecida, no mesmo ambiente, quando disponível?

Checklist do banco, do Windows e da rede

Banco de dados

• O comando que falhou, o código e a mensagem completa foram lidos juntos?
• O horário do log de erros do MySQL foi interpretado conforme a versão?

Windows e rede

• O ID do evento foi lido junto com a fonte, o canal e a descrição?
• Os eventos foram exportados com a máquina, o canal, o período e os filtros anotados?
• O teste de rede registrou a origem, o destino, os parâmetros e o horário com o fuso?

Checklist da linha do tempo e do registro

• Cada origem tem o período coberto, o fuso e a forma de coleta registrados?
• Os registros estão ligados por identificadores, e a ordem entre as origens é confiável?
• O atendimento separa a observação, a hipótese e a confirmação?
• O próximo teste tem a origem, o destino, a janela e os resultados que separam as hipóteses?

Glossário

• Base64: a representação de bytes como texto, usada para incluir arquivos em mensagens, sem nenhuma criptografia.
• Bloco: o conjunto de linhas de um mesmo registro, como uma mensagem formatada ou uma pilha de chamadas.
• Codificação: a regra que liga os caracteres aos bytes, como o UTF-8 e o Windows-1252.
• Coletor: o sistema que recebe e guarda os registros de várias origens.
• Contexto: os campos que distinguem uma operação das outras, como o terminal, o documento e a tentativa.
• Cópia de trabalho: a cópia do material que recebe os filtros, as ordenações e as formatações.
• Cópia preservada: a cópia do material coletado mantida sem nenhuma alteração.
• Correlação: a ligação de registros de origens diferentes pelo contexto e pelo tempo.
• Enviado: o marcador que o programa grava para o pedido, no momento definido pelo próprio programa.
• Escape: a forma de escrever um caractere especial dentro de um texto, como a barra antes das aspas em um JSON.
• Expressão regular: o padrão de busca de texto, com a sintaxe e as opções definidas pela ferramenta.
• Formatar: organizar a apresentação de uma mensagem com linhas e recuos, em uma cópia, sem mudar o original.
• Fronteira de palavra: o limite de uma expressão regular que impede encontrar só uma parte de um código mais longo.
• Fuso horário: a diferença entre a hora local e o UTC.
• ID do Evento: o número de um evento do Windows, lido junto com a fonte, o canal e a descrição.
• Kernel-Power 41: o evento gravado na inicialização depois de um encerramento incorreto do Windows.
• klogg: o leitor gratuito para a pesquisa em logs muito grandes.
• Linha do tempo: a sequência de registros de várias origens, com os horários originais e as conversões.
• Log: o conjunto de registros de eventos, em geral com a data e a hora, produzidos por um programa ou componente.
• Log de erros do MySQL: o registro da inicialização, do desligamento, da recuperação e dos erros do servidor.
• log_timestamps: a variável do MySQL, a partir do 5.7, que define o fuso das mensagens do log, com o UTC como padrão.
• Macro: a sequência de ações gravada para repetição.
• Marcador: a marca colocada em uma linha encontrada, usada para copiar ou remover as linhas marcadas.
• Monitoramento: o recurso do editor que atualiza a visualização quando o arquivo aberto muda.
• Nível de gravidade: a classificação que o programa dá à mensagem, como DEBUG, INFO, AVISO, ERRO ou CRÍTICO.
• Normalizar: substituir os campos variáveis de uma mensagem para agrupar as ocorrências do mesmo tipo.
• ObservedTimestamp: o campo do modelo do OpenTelemetry com o momento em que o coletor recebeu o registro.
• Pilha de chamadas: a sequência de chamadas ligada a uma exceção, chamada em inglês de stack trace.
• Primeira anomalia: o primeiro aviso, erro, repetição ou falta de etapa encontrado antes do sintoma.
• Recebido: o marcador que o programa grava para a resposta, no momento definido pelo próprio programa.
• Registro de várias linhas: o registro que continua nas linhas seguintes, em geral sem o prefixo de data e hora.
• Resultado de negócio: o que aconteceu com a operação solicitada, como o benefício autorizado ou recusado.
• Resultado desconhecido: a situação de uma operação cujo efeito o cliente não confirmou, diferente de uma recusa.
• Resultado técnico: a resposta da chamada, como o código HTTP ou uma exceção.
• Resumo criptográfico: o valor calculado sobre os bytes de um arquivo, como o SHA-256, que mostra se duas cópias são iguais.
• Rotação de log: a troca do arquivo de registros por data ou por tamanho.
• Select-String: o comando do PowerShell que pesquisa texto em arquivos, com a opção de contexto.
• SpanId: o identificador de uma etapa dentro de um percurso de processamento.
• Tail: a leitura do fim de um arquivo e das linhas acrescentadas a ele.
• Timestamp: o campo do modelo do OpenTelemetry com o horário informado pela origem.
• TraceId: o identificador de um percurso de processamento entre componentes.
• UTC: o Tempo Universal Coordenado, a referência dos fusos, indicado por Z ou por +00:00.
• WinMerge: o programa gratuito que compara arquivos lado a lado.

Para continuar estudando

• Centralização de logs: o envio dos registros de vários computadores para um coletor, como no protocolo syslog.
• Logs estruturados: os registros em JSON por linha, com campos fixos para a busca e para a contagem.
• Observabilidade: os logs, as métricas e o rastreamento distribuído, com o modelo do OpenTelemetry.
• Sincronismo de relógios: o NTP, as fontes de horário e o efeito do desvio dos relógios sobre os registros.
• Retenção e auditoria: o tempo de guarda dos registros, a proteção contra alterações e as exigências de segurança.

Referências

As referências a seguir reúnem as especificações da internet, a documentação da Microsoft, do MySQL e das ferramentas de leitura e os guias de gestão de logs que apoiam o conteúdo de logs. O material está em inglês.

Logs e coleta

• IETF, RFC 5424, The Syslog Protocol: o produtor, o coletor e o transporte, sem garantia de entrega;
• NIST, SP 800-92: a gestão de logs, com a seleção das origens, a análise e a preservação;
• OpenTelemetry, Logs Data Model: a gravidade, os atributos, o Timestamp e o ObservedTimestamp;
• W3C, Trace Context: o TraceId, o SpanId e a propagação do contexto entre componentes.

Tempo e preservação

• IETF, RFC 3339: a data completa, o UTC e os deslocamentos de fuso;
• Microsoft, carimbos de tempo de alta resolução: o relógio sincronizável e o contador usado para medir intervalos;
• Microsoft, Get-FileHash: o resumo SHA-256 de um arquivo, padrão do comando.

Ferramentas de leitura

• Notepad++, manual de pesquisa: os modos de busca, a contagem, a marcação e os marcadores;
• Notepad++, interface do usuário: os menus, a quebra de linha e o monitoramento do documento;
• klogg: a pesquisa em arquivos grandes com expressões regulares;
• Microsoft, Get-Content: os parâmetros Tail, Wait e Encoding;
• Microsoft, Select-String: a pesquisa por linha, o texto literal e o contexto;
• WinMerge, comparação de arquivos: a comparação lado a lado e as opções que ignoram diferenças.

Integrações e mensagens

• IETF, RFC 9110, HTTP Semantics: os códigos de situação, o 401 e a repetição dos métodos idempotentes;
• IETF, RFC 8259, JSON: os valores, as estruturas, os escapes e os nomes repetidos;
• W3C, Namespaces in XML: a identidade dos elementos pelo espaço de nomes e pelo nome local;
• W3C, XML 1.0, tratamento dos espaços: os espaços que fazem parte do conteúdo;
• W3C, XML Signature 1.1: as transformações e a verificação da assinatura.

Banco de dados

• MySQL, mensagens de erro do servidor: os códigos 1045, 1054, 1062, 1146, 1205 e 1213;
• MySQL, mensagens de erro do cliente: os códigos 2006 e 2013;
• MySQL, tratamento de erros do InnoDB: o que o tempo de espera esgotado e o deadlock desfazem;
• MySQL, log de erros: os eventos e os destinos do log do servidor;
• MySQL, formato do log de erros: a variável log_timestamps, com o UTC como padrão.

Windows e rede

• Microsoft, Kernel-Power ID 41: o registro na inicialização seguinte e os limites da evidência;
• Microsoft, falhas de programas e serviços: a leitura dos eventos de falha, com o módulo e a exceção;
• Microsoft, Get-WinEvent: as consultas e os filtros por fonte e por período;
• Microsoft, wevtutil: a consulta e a exportação dos eventos;
• Microsoft, comando ping: o eco ICMP, os parâmetros e as estatísticas;
• Microsoft, Test-NetConnection: o teste de porta TCP;
• Microsoft, Get-Date: a formatação da data e do horário com o fuso.