Um bom runbook faz a diferença entre um turno de on-call tranquilo e um desastre às 3 da manhã. Com a Trupeer, pode poupar horas na escrita de runbooks de TI começando com um modelo de runbook gratuito, personalizando-o com as suas orientações de marca e transformando runbooks longos em walkthroughs em vídeo que os engenheiros de on-call conseguem analisar em segundos.

O que é um modelo de runbook gratuito?

Um modelo de runbook gratuito é uma estrutura reutilizável para a sequência de passos que permite concluir uma tarefa operacional específica: uma implementação, um failover, uma migração, uma recuperação, uma janela de manutenção agendada.

A palavra runbook vale a pena ser levada ao pé da letra. É um documento que se executa, não que se lê. Fica aberto num ecrã enquanto o trabalho acontece, é seguido pela ordem certa e o seu valor está totalmente no que faz durante a execução, e não no que diz quando é arquivado.

Esse facto único separa um bom runbook de um bom documento de procedimento, e é a coisa que a maioria dos modelos falha. Eles produzem uma descrição bem organizada do que fazer, que é necessária e corresponde a aproximadamente metade do que um runbook tem de ter.

A outra metade é que um runbook é um formato. Preenche-se à medida que é executado, porque o registo do que aconteceu de facto é o que faz a diferença entre uma operação que alguém consegue assumir a meio e uma que tem de ser reiniciada ou adivinhada.

O formato segue isso. Um ficheiro Excel de modelo de runbook gratuito adapta-se à tabela de passos com as colunas de resultado e timestamp, e é o que a maioria das equipas acaba por usar. Uma versão Word de modelo de runbook gratuito adapta-se a runbooks com muito contexto e texto em torno dos passos, e um ficheiro Microsoft Word de modelo de runbook gratuito é a mesma coisa com o seu nome mais longo. Um modelo de runbook gratuito em PDF é um registo arquivado de uma execução concluída, em vez de um documento de trabalho.

Runbook de implementação ou runbook de incidente?

Dois documentos partilham o mesmo nome e são usados de formas opostas, por isso decida qual é o que está a escrever.

Um modelo de runbook de implementação cobre trabalho planeado. Um release, uma migração, um cutover, uma janela de manutenção agendada. É executado do primeiro passo até ao fim, pela ordem certa, num momento que toda a gente já sabia, normalmente por mais do que uma pessoa e muitas vezes durante a transição de turno. O problema de design é a sequência, o estado e a passagem de responsabilidade.

Um runbook de incidente ou de on call cobre trabalho não planeado. Algo está errado e alguém está a diagnosticar. É introduzido num ponto imprevisível, por quem estiver disponível, sob pressão, e não é lido pela ordem. O problema de design é encontrar rapidamente a secção relevante, o que o torna mais parecido com um documento de consulta do que com um guião.

A maioria dos modelos publicados mistura os dois e não serve bem nenhum. Um runbook de diagnóstico forçado a uma sequência numerada não pode ser introduzido a meio, e um runbook de implementação organizado como um conjunto de sintomas perde a ordenação que o torna seguro.

Esta página é sobretudo sobre o primeiro. Trabalho planeado, executado pela ordem certa, em que as falhas dispendiosas têm a ver com estado e passagem de responsabilidade, e não com diagnóstico.

Como personalizar este modelo na Trupeer

Passo 1: Abrir a secção de Templates

Vá à secção Templates no menu principal.

Passo 2: Selecionar e abrir um modelo

Clique em qualquer modelo com que queira trabalhar para o abrir.

Passo 3: Expandir a vista do modelo

Se necessário, expanda a vista do modelo para ver o layout completo e os detalhes com clareza.

Passo 4: Editar o modelo

Clique em Edit para começar a modificar o modelo selecionado.

No editor, pode:

• Adicionar novas secções

• Definir ou atualizar regras de formatação

• Adicionar um logótipo e ajustar a sua posição e definições relacionadas

Passo 5: Guardar o seu modelo personalizado

Depois de fazer todas as alterações necessárias, clique em Save para guardar o modelo atualizado como seu.

Passo 6: Pré-visualizar e afinar o modelo

Quando quiser ver como fica o seu modelo personalizado, abra a opção Preview.

A partir do ecrã de pré-visualização, pode continuar a fazer ajustes diretamente, se necessário, garantindo que o modelo aparece exatamente como o quer.

Com um modelo de runbook pode:

• Poupar horas na escrita: Ignore a página em branco com uma estrutura criada para procedimentos de operações.

• Reduzir o MTTR: Runbooks claros ajudam os engenheiros de on-call a resolver incidentes mais rapidamente.

• Manter-se alinhado com a marca: Aplique o seu logótipo, fontes e cores usando o kit de marca da Trupeer.

• Formar novos engenheiros: Combine runbooks com walkthroughs em vídeo para integrar equipas de operações mais rapidamente.

• Uniformizar entre equipas: Use o mesmo formato de runbook para cada tipo de incidente.

• Aceder a equipas globais: Traduza runbooks para 65+ idiomas com um clique.

Escreva o runbook para ser entregue a meio

Aqui está a restrição de design à volta da qual vale a pena construir. A certa altura durante a execução, a pessoa que está a correr o runbook deixa de ser a pessoa que o começou.

O turno termina. Alguém é chamado. Uma janela dura mais do que o planeado. Em qualquer operação que dure mais do que algumas horas, isto é normal e não excecional, e é o momento em que os runbooks falham de forma dispendiosa.

A pergunta contra a qual é preciso desenhar é precisa. Uma segunda pessoa consegue assumir a partir do passo trinta e sete, sem um briefing verbal, e prosseguir em segurança?

Responder que sim exige quatro coisas que a maioria dos modelos não tem.

Um resultado real registado por passo, não apenas um resultado esperado. Um visto significa que alguém clicou em algo. Não diz à próxima pessoa o que aconteceu.

Um timestamp por passo, porque há muito frequentemente o facto mais diagnóstico disponível é há quanto tempo é que um passo foi executado.

Uma marcação explícita de quais os passos que são seguros para repetir. A primeira pergunta de qualquer pessoa que assuma é se o passo anterior terminou de facto. Se for seguro repetir, então essa pergunta deixa de ser relevante, o que vale muito mais do que custa registar.

Um ponto de não retorno declarado. Depois do qual o rollback já não está disponível. Alguém que chegue a meio da execução precisa de saber de que lado dessa linha está antes de tocar em qualquer coisa.

Adicione essas quatro e a passagem verbal deixa de ser o mecanismo. O documento torna-se a passagem de responsabilidade, que é a única versão que sobrevive a alguém estar cansado, apressado ou indisponível.

O que um modelo de runbook tem de conter

Nove componentes. As quatro do meio são as que distinguem um runbook de um procedimento.

O último merece atenção. Passos de verificação escritos como "confirmar que o site está ativo" passam quando o site está ativo e errado, que é a falha descrita abaixo.

Modelo de runbook gratuito: a estrutura para copiar

Preenchido com um exemplo real em vez de placeholders. É um excerto de uma migração de um sistema de gestão de encomendas.

Copie daqui.

Cabeçalho e janela. Nome do run, data, janela planeada, prazo de abortar e a versão deste runbook.

Migração do sistema de gestão de encomendas. Sábado, 14 de junho. Janela 06:00 a 20:00. Prazo de abortar 16:00, após o qual fazemos rollback independentemente do progresso. Runbook v9.

Funções para este run. Com números no documento.

A executar: K Ferreira 06:00 a 14:00, depois D Attwood 14:00 a 20:00. Ponto de não retorno aprovado por: Head of Engineering, 07700 900xxx. Escalada: líder da plataforma de on call, 07700 900xxx. Contacto do negócio para a decisão de avançar: Trading Director.

Pré-condições. Todas confirmadas antes do passo um.

Foi efetuada uma cópia de segurança completa da base de dados e o restauro foi testado na instância standby. Freeze de código em vigor desde quinta-feira. Ambos os executores têm acesso à produção verificado hoje, não assumido. Rollback ensaiado em staging a 7 de junho.

Linha de estado. Atualizada à medida que avança, mantida no topo.

Atualmente no passo 37. A correr desde 13:48. Executor: K Ferreira. Ponto de não retorno ainda não passou.

Tabela de passos.

Rollback. Disponível até e incluindo o passo 37. Restaurar a partir da cópia de segurança do pré-run, apontar novamente o DNS, reiniciar os workers de receção. Ensaiado em staging a 7 de junho por D Attwood.

Secção de passagem de responsabilidade. Preenchida antes de alguém sair.

Concluído até ao passo 35. O passo 34 falhou silenciosamente na primeira tentativa com uma divergência de contagem e foi repetido com sucesso; as contagens agora correspondem a 84,120. Observe novamente a contagem do índice após o passo 36, uma vez que falhou uma vez. Nada em curso. O ponto de não retorno ainda não passou, pelo que o rollback continua disponível.

Verificação. Detalhada o suficiente para falhar.

O site carrega. A contagem de produtos nas páginas de categorias soma 84,120. Dez encomendas de exemplo colocadas ponta a ponta. Histórico de encomendas visível para cinco contas conhecidas. O relatório de reconciliação de pagamentos é executado e corresponde.

Copie daqui.

Exemplo de runbook: sessenta e um passos e uma passagem de responsabilidade de dez minutos

A Tamworth Retail Group, um retalhista online, migrou o seu sistema de gestão de encomendas durante uma janela planeada de catorze horas num sábado.

O runbook tinha sessenta e um passos. Foi revisto, ensaiado em staging e era um documento genuinamente cuidadoso. A sua tabela de passos tinha três colunas: número do passo, ação e uma caixa de verificação.

O primeiro engenheiro executou os passos um a trinta e sete, fez a passagem de responsabilidade verbalmente em cerca de dez minutos na transição de turno e foi para casa depois de um dia longo.

O passo trinta e quatro era o reindexar do catálogo de produtos, um job que demorava cerca de quarenta minutos. Ele tinha começado, não viu erros e marcou com um visto. Na verdade, falhou a cerca de oitenta por cento e não reportou nada.

O segundo engenheiro chegou a uma lista de sessenta e um passos com vistos nos primeiros trinta e sete. Não havia registo do que cada passo produziu, não havia timestamps e não havia indicação de quais os passos que podiam ser repetidos em segurança. Tudo o que estava antes do passo trinta e oito estava, para o documento, simplesmente feito.

Ela continuou. O catálogo estava indexado parcialmente, o que significava que cerca de doze por cento dos produtos estavam invisíveis no site quando este reabriu.

O teste de fumo no fim confirmou que o site carregava. Não comparou a contagem de produtos com a contagem do catálogo, por isso passou.

Ninguém reparou até à segunda-feira de manhã, trinta e uma horas depois, durante o fim de semana de maior atividade comercial do trimestre. As encomendas perdidas estimadas face ao mesmo fim de semana do ano anterior chegaram a cerca de duzentas e quarenta mil libras.

Não conseguiram fazer rollback. O ponto de não retorno tinha sido ultrapassado no passo quarenta e um e, embora toda a gente envolvida soubesse isso em princípio, ficou registado num parágrafo na página um e não no passo em que aconteceu.

A reescrita não adicionou passos. Adicionou colunas. Resultado real, timestamp e uma marcação de seguro para repetir em cada passo. Uma linha de estado no topo. O ponto de não retorno passou da introdução para o próprio passo, a negrito. E uma secção de passagem de responsabilidade que tem de ser concluída antes de alguém sair, o que transformou uma conversa de dez minutos em quatro linhas escritas.

Na próxima migração, a transição de turno aconteceu na hora nove. A passagem de responsabilidade demorou quatro minutos. O engenheiro que assumiu repetiu três passos de que não tinha certeza, especificamente porque estavam marcados como seguros para repetir, e o run terminou dentro da janela.

Repetir três passos por precaução custa alguns minutos. Não conseguir fazê-lo é o que custa um fim de semana.

Como escrever um runbook em seis passos

1. Escreva os passos executando a tarefa, não a partir da memória. Um runbook escrito numa secretária contém os passos de que o autor se lembra e omite os que as suas mãos fazem automaticamente.

2. Dê a cada passo um resultado esperado. O que vai ver que significa que funcionou. Um passo sem resultado esperado não pode ser verificado por ninguém além do seu autor.

3. Marque cada passo como seguro para repetir ou não. Está descrito abaixo. Esta é a coluna mais barata para adicionar e a mais valiosa durante uma passagem de responsabilidade.

4. Coloque o ponto de não retorno no passo, a negrito. Não na introdução, onde será lido uma vez por alguém que não é a pessoa que precisa dele.

5. Adicione as colunas que preenche durante o run. Resultado real e timestamp. Se não estiverem no documento, não serão registadas em lado nenhum.

6. Ensaie, incluindo o rollback. Um rollback que só foi escrito é uma suposição. Ensaie em staging com a pessoa que o vai executar, e não com a pessoa que o escreveu.

O passo um é o que separa runbooks úteis dos plausíveis. Escrever enquanto faz apanha o clique não documentado, as credenciais que já estavam na área de transferência e a tab que tinha de estar aberta.

Marcar passos como seguros para repetir e o ponto de não retorno

Estas duas marcações fazem a maior parte do trabalho numa passagem de responsabilidade e nenhuma aparece num modelo típico.

Seguro para repetir. Para cada passo, pode ser executado duas vezes sem causar danos. Reiniciar um serviço parado, repetir um índice, aplicar novamente uma configuração que já está aplicada: normalmente sim. Enviar um email a um cliente, incrementar um contador, migrar linhas para uma tabela que não remove duplicados: normalmente não.

O valor é que elimina a pergunta que a pessoa que assume não consegue responder. O passo anterior terminou. Se a resposta não importar, porque repetir é inofensivo, então ninguém tem de o estabelecer sob pressão com informação incompleta.

Quando um passo não é seguro para repetir, diga o que deve verificar primeiro. "Não, verifique a contagem de linhas antes de repetir" é muito mais útil do que "Não", porque a pessoa que o lê já decidiu que precisa de fazer alguma coisa.

O ponto de não retorno. Cada run que altera o estado tem um. É o passo após o qual o rollback já não está disponível, ou já não é mais barato do que seguir em frente.

Marque-o no passo, de forma visualmente distinta, para que alguém a percorrer o documento consiga ver de que lado está. Dê o nome de quem autoriza a passagem e registe a hora em que foi ultrapassado na coluna de resultado real. Muitos runs têm mais do que um; nesse caso, marque cada um e diga o que cada um fecha.

A razão para registar a ultrapassagem em vez de apenas marcar o passo é que, após um incidente, a pergunta sobre quando a decisão se tornou irreversível é feita, e ninguém se lembra.

Variantes de modelo de runbook

A estrutura mantém-se e a ênfase muda.

Modelo de runbook de implementação. O exemplo acima. Sequencial, planeado, frequentemente a atravessar um turno, e a variante em que o design da passagem de responsabilidade é o que mais importa.

Runbook de recuperação de desastre. Executado raramente e nas piores condições, pelo que se degrada de forma invisível entre utilizações. O requisito distintivo é o ensaio agendado, já que um runbook de DR que não foi executado num ano deve ser assumido como errado.

Runbook de on call e de incidente. É introduzido num ponto imprevisível em vez de ser executado pela ordem. Organize por sintoma e não por sequência, mantenha cada entrada curta e ligue ao material mais profundo em vez de o conter.

Runbook de manutenção agendada. Repetido regularmente, o que o torna a variante que melhora de facto com o uso, desde que alguém o atualize durante o run em vez de pretender fazê-lo depois.

Runbook de onboarding e offboarding. Muitas vezes é o primeiro runbook que uma equipa escreve, porque a sequência é estável e o custo de falhar um passo, especialmente no offboarding, é um problema de segurança e não um mero incómodo.

Para qualquer coisa que cubra sistemas regulamentados, processamento financeiro ou controlos relacionados com segurança, um runbook normalmente fica dentro de um processo de gestão de alterações com requisitos próprios de aprovação e registo, e esses regem em vez de qualquer coisa nesta página.

Runbook, instrução de trabalho ou SOP?

Três documentos que se sobrepõem e vale a pena separar, porque escolher mal produz o conteúdo certo num formato inutilizável.

Um procedimento padrão de operação cobre um processo ao nível de quem faz o quê e em que ordem, normalmente abrangendo funções e muitas vezes abrangendo dias. É lido para compreensão.

Uma instrução de trabalho cobre uma tarefa em detalhe para a pessoa que a executa e é escrita para ser seguida por alguém que pode não estar familiarizado com ela. O modelo de instruções de trabalho cobre esse documento.

Um runbook é uma instrução de trabalho que também é um registo de execução. É seguido e preenchido em simultâneo; normalmente abrange várias tarefas numa ordem definida, e as suas colunas existem para deixar rasto.

Se o seu documento for lido antes do trabalho e arquivado depois, é um procedimento. Se estiver aberto durante o trabalho e for diferente no fim do que era no início, é um runbook.

Manter os runbooks atualizados

Os runbooks degradam-se mais depressa do que a maioria da documentação porque descrevem sistemas que mudam, e essa degradação é invisível até ao run que falha.

O mecanismo que realmente funciona é atualizar durante a execução e não depois. Quem executa o runbook tem o documento aberto, acabou de descobrir que o passo doze agora exige uma confirmação extra e é a única pessoa que alguma vez vai saber isso de forma tão barata. Dez segundos depois, ou uma hora de confusão no próximo run.

Torne isso legítimo dizendo-o explicitamente no topo do documento e tratando um runbook inalterado após uma execução real como ligeiramente suspeito, em vez de como um sinal de qualidade.

A automação é o outro caminho, e vale a pena encará-la com clareza. Automatizar um passo de runbook remove o erro humano e o problema de documentação em conjunto, o que é genuinamente melhor onde se aplica. O que não remove é a necessidade do documento envolvente, porque alguém ainda tem de saber o que fazer quando a automação falha, e essa pessoa agora está menos habituada do que antes. Automatize os passos, mantenha o runbook e certifique-se de que o runbook cobre a parte automatizada quando falha.

O que um modelo de runbook gratuito não consegue resolver

Um runbook escrito a partir da memória. Nenhum modelo mostra os passos que o autor faz sem pensar. Só escrever enquanto executa.

Um rollback não ensaiado. Um plano de rollback que nunca foi executado é uma hipótese, e o meio de uma migração falhada é um local pobre para o testar.

Uma checklist com o nome. Grande parte do que circula como modelo de runbook gratuito para download é um procedimento numerado com caixas de verificação, que é um documento diferente e mais fraco.

Verificação que não pode falhar. "Confirmar que o site está ativo" passa quando o site está ativo e errado. Cada passo de verificação deve ser específico o suficiente para conseguir imaginar que falha.

Uma janela sem prazo de abortar. Sem um, um run que está a correr mal continua, porque parar parece sempre mais caro do que o próximo passo. Defina o prazo antes de começar, quando ninguém está investido.

Mostrar o run em vez de o descrever

Os runbooks são executados por pessoas que os executam raramente. Uma migração acontece duas vezes por ano. Um teste de DR acontece anualmente. A pessoa que o executa já o fez uma vez antes, possivelmente nunca.

É exatamente o tipo de caso em que um procedimento escrito serve pior, porque o leitor tem de reconstruir uma sequência de ecrãs e estados da consola a partir de texto, e a diferença entre o que o autor quis dizer e o que o leitor imagina é onde o passo não documentado se esconde.

A Trupeer AI resolve isso. Alguém executa o run uma vez, em staging, enquanto grava, e o resultado é um walkthrough passo a passo escrito com screenshots já capturados e colocados, juntamente com um vídeo, na sua própria identidade de marca. A versão escrita torna-se o runbook. O vídeo é o que a pessoa que executa vê no dia anterior, que é a preparação que ninguém tem atualmente tempo para produzir.

Registe-o. Dê-lhe marca. Traduza-o. Faça-o com a Trupeer.

Duas coisas seguem-se que importam especificamente para runbooks. O ensaio produz a documentação como subproduto e não como uma tarefa adicional, que é a única versão de documentação que acontece de forma fiável. E quando a infraestrutura muda, voltar a gravar o ensaio é mais rápido do que editar screenshots, pelo que o runbook tem mais probabilidade de estar atualizado no momento em que isso importa.

O material fica na sua base de conhecimento e funciona também como formação para quem estiver na escala a seguir. As evidências de verificação e os controlos de qualidade em torno do run pertencem ao plano de QA. A consistência com os seus outros documentos é uma questão de definir o kit de marca uma vez, e a configuração é coberta no guia de configuração do modelo de documento.

Perguntas Frequentes

Existe uma versão Excel gratuita do modelo de runbook?

O Excel é o que a maioria das equipas acaba por usar e adapta-se bem ao documento, porque o núcleo de um runbook é uma tabela que preenche enquanto trabalha. Um ficheiro Excel de modelo de runbook gratuito trata naturalmente as colunas do passo, resultado esperado, resultado real, timestamp e seguro para repetir, e permite que várias pessoas vejam a mesma folha durante um run.

Duas definições práticas. Fixe a linha do cabeçalho e coloque a linha de estado nas duas primeiras linhas acima dela para continuar visível enquanto faz scroll. Um ficheiro Excel de modelo de runbook gratuito em que o passo atual sai do ecrã perde grande parte do valor na passagem de responsabilidade.

Existe uma versão Word gratuita do modelo de runbook?

O Word adapta-se a runbooks com um contexto substancial em torno dos passos: notas de arquitetura, histórico de decisões, detalhes de escalada. Construa o ficheiro Word do modelo de runbook gratuito primeiro com as secções narrativas e depois com a tabela de passos.

A limitação é preenchê-lo durante um run. Uma tabela do Word é mais lenta a atualizar do que uma célula de folha de cálculo, e durante uma migração em direto essa fricção é suficiente para impedir que as pessoas registem resultados reais. Muitas equipas mantêm o contexto num documento Word de modelo de runbook e a tabela de passos numa folha de cálculo ligada a partir dele.

Existe uma versão Microsoft Word gratuita do modelo de runbook?

Sim, e aplica-se a mesma troca. Um ficheiro Microsoft Word de modelo de runbook gratuito é a escolha certa quando o runbook é revisto e aprovado como parte de um processo de alterações, já que os documentos se encaixam melhor em fluxos de aprovação do que as folhas de cálculo.

Se seguir esse caminho, adicione as colunas de resultado real e timestamp mesmo assim. Um runbook aprovado sem elas será executado sem elas e o registo de que precisava não existirá.

Existe um modelo de runbook de implementação?

Um modelo de runbook de implementação é a variante sequencial abordada ao longo desta página: trabalho planeado, executado pela ordem certa, normalmente a atravessar um turno.

Quatro coisas distinguem um bom modelo de um modelo genérico. Um ponto de não retorno marcado no passo e não na introdução. Uma marcação seguro para repetir em cada passo. Colunas de resultado real e timestamp. E uma secção de passagem de responsabilidade que é concluída antes de alguém sair. Quase nenhum modelo publicado tem qualquer uma das quatro.

Existe um modelo de runbook gratuito em PDF?

O PDF é o arquivo e não o documento de trabalho. Quando um run está concluído, exporte o runbook preenchido como um modelo de runbook gratuito em PDF e anexe-o ao registo de alteração, porque um runbook concluído com timestamps e resultados reais é a melhor evidência do que aconteceu que alguma vez terá.

Não execute a partir de um PDF. O documento tem de ser escrito durante o run e tudo o que não conseguir escrever não será registado.

Existe um modelo de runbook gratuito para download que valha a pena usar?

A própria tabela demora dez minutos a construir, por isso um modelo de runbook gratuito para download está a poupar pouco, e a maioria dos publicados são documentos de procedimento com uma etiqueta de runbook.

Verifique uma coisa antes de adotar qualquer um deles. Veja se a tabela de passos tem uma coluna para o que aconteceu de facto. Se tiver apenas uma caixa de verificação, tem uma checklist e todo o argumento desta página é que a diferença entre essas duas é o que a passagem de responsabilidade depende.

Quanto tempo deve ter um runbook?

Tanto quanto o run, que para uma migração substancial são genuinamente dezenas de passos. O problema não é o comprimento dos runbooks.

O que deve controlar é o tamanho dos passos. Um passo deve ser uma ação com um resultado observável. Passos que agrupam várias ações não podem ser entregues a meio, porque a próxima pessoa não consegue dizer quanto do conjunto aconteceu, e é exatamente essa situação que o documento existe para evitar.

Quem deve escrever o runbook?

Quem o vai executar, escrevendo enquanto o executa num ambiente não produtivo. Um runbook escrito por um arquiteto e executado por um engenheiro vai estar a faltar precisamente os passos que o arquiteto não executa pessoalmente.

Depois, tenha uma segunda pessoa a executar o rascunho em staging sem ajuda do autor. Cada pergunta que tiver de fazer é uma falha, e a correção é escrevê-la em vez de responder.