Relatar um achado de desempenho sem exagerar: linha de base, janela do incidente, ferramenta e intervalo

Objetivo

Documentar uma observação de desempenho de modo que outro agente ou operador consiga avaliar o quanto pode confiar nela e reproduzir a medição, sem dar a entender que houve um experimento controlado que na verdade não foi realizado.

Pré-requisitos

A saída bruta, e não apenas um resumo, de todas as ferramentas usadas tanto no período normal quanto durante o incidente.

Passos

1. Apresente primeiro a linha de base: os números de um período em que o sistema era considerado saudável, com a ferramenta, a invocação exata (flags e intervalo) e a janela de tempo real (relógio de parede) amostrada.
2. Apresente os números do incidente da mesma forma, com a mesma ferramenta e o mesmo intervalo, sempre que possível. Uma linha de base obtida com vmstat 1 5 e uma leitura do incidente feita com um intervalo de 10 minutos do sar não são diretamente comparáveis, e o relatório deve dizê-lo explicitamente, em vez de sugerir que são.
3. Indique a janela de tempo com precisão, incluindo o fuso horário ou UTC explícito, para que o leitor possa obter de forma independente a mesma janela em qualquer outra fonte (logs, alertas, histórico de deploys) que cubra o mesmo período.
4. Liste o que foi descartado e como: "A CPU não estava saturada (as amostras de 1 segundo do mpstat ficaram abaixo de 40% em todos os núcleos durante a janela)" é um fato verificado nessa resolução; "provavelmente não é CPU" é um palpite e deve ser identificado como tal. Uma média só descarta aquilo que ela poderia ter mostrado: um intervalo de 10 minutos do sar não consegue excluir uma saturação que dure poucos segundos, e uma CPU baixa em um guest não diz nada sobre steal, a menos que %steal também tenha sido lido.
5. Mantenha os dois tipos de afirmação claramente separados: de um lado, os números lidos diretamente da saída de uma ferramenta; de outro, a interpretação construída sobre eles. "O iowait estava elevado" é uma leitura; "isso é causado pelo job de backup" é uma hipótese, a menos que o log do próprio backup confirme o horário, e mesmo um horário coincidente mostra apenas coincidência, não causa, até que alterar o suspeito altere a medição.
6. Anexe ou referencie as capturas brutas (um .blg, um arquivo perf.data, um arquivo binário salvo do sar, uma transcrição do terminal) em vez de apenas os números extraídos, para que a leitura possa ser conferida depois.
7. Registre o que não foi medido e ainda poderia explicar o achado, em vez de sugerir que a investigação foi exaustiva, e mencione qualquer ferramenta cujo próprio overhead (strace, um perf record de alta frequência) possa ter alterado os números.
8. Se for alegado que houve uma correção, mostre a mesma medição antes e depois, sob carga comparável; uma única execução melhor após uma mudança é uma observação, não uma prova.

Resultado esperado

Um relatório que um segundo leitor consegue avaliar por conta própria (mesma ferramenta, mesmo intervalo, mesma janela e uma lista explícita do que foi descartado), sem precisar confiar nos julgamentos subjetivos do primeiro investigador.

Limites e base de verificação

Esta é uma disciplina de redação proposta, não um padrão; nenhum formato único é usado universalmente entre ferramentas e equipes. Ela não valida, por si só, que as medições subjacentes estavam corretas; apenas garante que o que foi medido e o que foi inferido continuem distinguíveis para o leitor.