Um manual de execução mensal para um relatório de backlinks

Por que mensal e não diário

Nosso gráfico é atualizado aproximadamente uma vez por mês. Uma execução diária retorna os mesmos números.

Executar com mais frequência não torna um relatório mais atual, apenas mais caro de explicar. Um leitor que vê 30 pontos idênticos assumirá que o pipeline está com defeito.

Escolha um dia específico do mês deliberadamente, idealmente uma semana após a estabilização da atualização anterior. Escreva a data no nome do arquivo, para que o próprio agendamento fique documentado.

Escolha o calendário primeiro e deixe o relatório segui-lo. Um relatório que é reconstruído sempre que alguém abre o notebook não tem uma data clara, o que é difícil de defender em uma revisão.

O que armazenar além dos números

Metade do relatório é metadados, então armazene-os junto com os números.

Registre a data da coleta, o nome da ação, os parâmetros (per, sort, order) e o campo de créditos da resposta em um pequeno arquivo auxiliar ao lado de cada captura instantânea. Seis meses depois, quando um colega perguntar por que outubro parece diferente de setembro, esse arquivo responderá em dez segundos em vez de uma tarde inteira.

Adicione o commit do git do script e as versões dos pacotes do renv. Um relatório que não consegue indicar qual código e qual estado do índice produziram um gráfico é uma captura de tela, não uma análise, não importa quão organizado pareça o tibble.

Uma estrutura mínima de targets

Três targets são suficientes quando o plano permanece pequeno.

Um target coleta da API e grava o arquivo datado, um lê o arquivo e constrói o tibble, um renderiza o documento Quarto. Como apenas o primeiro target toca a rede, você pode executar os outros offline quantas vezes quiser e o gráfico nunca mudará por acidente.

Fixe as versões dos pacotes com renv, registre as informações da sessão no rodapé do relatório e mantenha a tabela de limiares da página de pontuação em massa no repositório ao lado do código. Para o lado financeiro, a página de orçamento mostra quanto um mês deve custar.

Quando algo falhar, leia o código primeiro. HTTP 401 significa que a chave está errada ou ausente. HTTP 402 significa que os créditos acabaram. Qualquer outra coisa vale a pena registrar por completo. O teardown cobre essas etapas, e o exemplo de join é um bom primeiro job para agendar.

Saber que uma execução falhou antes que um colega saiba

Um relatório de backlinks reproduzível que falha silenciosamente engana mais do que um que nunca foi executado. A verdadeira pergunta não é se o job pode falhar, mas quão rápido alguém fica sabendo disso.

Faça o job falhar de forma visível

Um job agendado sai com um status diferente de zero quando uma chamada retorna HTTP 401 ou 402, e o agendador marca a execução como falha. Esse é o alerta mais barato que você tem, e não precisa de serviço extra.

Coletas parciais são o caso perigoso. Se o script grava seu arquivo após vinte dos trinta chunks, o arquivo existe e parece normal. Escreva em um nome temporário e renomeie-o apenas no sucesso.

Envie uma mensagem por falha

Escolha um canal para falhas, como um e-mail para o proprietário do relatório ou uma mensagem no chat da equipe. Dois canais significam dois lugares para procurar, e uma maior chance de ninguém olhar em nenhum deles.

A mensagem deve nomear o target que falhou, o código de status e o horário. Tudo o resto pertence ao log.

Verifique se a saída é plausível

Uma execução pode ser bem-sucedida e ainda assim estar errada. Compare a contagem de linhas com a do mês anterior e sinalize uma queda além de um limiar que você escolheu antecipadamente.

A verificação pode ser tão simples quanto uma faixa esperada. O objetivo é notar uma captura instantânea meio vazia antes que um gráfico chegue a um cliente.

Nomeie um proprietário para o relatório

Nomeie um proprietário para o relatório. Um alerta sem proprietário é lido por todos e não é acionado por ninguém.

O proprietário não precisa consertar o job. O proprietário precisa decidir se um relatório atrasado é aceitável e dizer isso no próprio relatório.

Escreva o nome do proprietário no cabeçalho do manual de execução e atualize-o quando o proprietário mudar. Um manual de execução com um ex-proprietário é um perigo silencioso.

Escolhendo o dia e executando o primeiro job manualmente

O timing e a primeira execução decidem se o agendamento se sustenta. Ambos são fáceis de errar no primeiro mês, e ambos são baratos de acertar.

Duas decisões, escritas uma vez, economizam a maioria dos argumentos depois. A primeira é o dia. A segunda é onde o cronômetro executa. Ambos pertencem ao manual de execução, não à cabeça de ninguém.

Escolha um dia e anote

Um dia fixo no mês, como o primeiro dia útil após a estabilização da atualização, é mais fácil de explicar do que um palpite no início do mês.

Coloque o dia no próprio arquivo de agendamento, para que o timing faça parte do código e não uma memória no calendário de alguém.

Execute o primeiro job manualmente

A primeira execução agendada deve ser manual. Execute o script você mesmo, leia o log, compare o arquivo com o anterior e só então passe o cronômetro para o agendamento.

A primeira execução também testa o armazenamento de segredos. Uma chave que funciona na sua máquina, mas está ausente no CI, é uma razão comum para a primeira falha agendada.

Mantenha o arquivo auxiliar honesto

O arquivo auxiliar registra o que a execução fez. Se uma pessoa o escreve à mão, ele se desvia da execução. Faça o script escrevê-lo e deixe as pessoas apenas lê-lo.

Um arquivo auxiliar que o script nunca tocou é uma nota, não um registro, e o relatório deve citar o registro.

Compare o arquivo auxiliar com o arquivo uma vez por mês. Se os números nos dois discordarem, a execução falhou de uma maneira que o script não notou.

Onde o cronômetro vive

Um executor hospedado e uma entrada cron local falham de maneiras diferentes. Um executor hospedado pode ser pausado por suas próprias configurações, e uma entrada cron local para quando o computador está em suspensão. Verifique qual você escolheu e teste o cronômetro uma vez com um agendamento curto antes do real.

Qualquer que seja sua escolha, anote o cronômetro no repositório ao lado do script, para que a próxima pessoa saiba onde o job vive.