Por que a documentação do SRE é importante. Parte 3

Boa noite a todos! Temos pressa em compartilhar as notícias de que, em fevereiro, lançaremos um novo fluxo no curso Devops - Practices and Tools , o que significa que é hora de terminar o que começamos e publicar a terceira parte do artigo: “Por que a documentação do SRE é importante” . Vamos lá!

Documentos para gerenciar comandos SRE

As equipes de SRE precisam de documentação confiável e acessível para trabalhar com eficiência.

Site da equipe

Nota: Em vez do site, você pode usar um espaço ou seção separada no Confluence / Wiki.

O site da equipe é importante porque fornece coordenação de informações e documentação relacionadas à equipe do SRE e seus projetos. Por exemplo, no Google, muitas equipes de SRE usam o g3doc (uma plataforma de documentação interna do Google, onde as docas vivem no código-fonte com o código associado), e algumas equipes usam o g3doc e o Google Sites: nesse caso, as páginas do g3doc estão intimamente relacionadas ao código / detalhes da implementação.

Estatuto da equipe



As equipes de SRE devem apoiar uma carta publicada que descreve a motivação para o trabalho e documenta o envolvimento contínuo. O estatuto é necessário para estabelecer a identidade, os principais objetivos e o valor da equipe em toda a empresa.

A carta geralmente possui os seguintes elementos:

• Uma descrição de alto nível da área de responsabilidade da equipe. Incluindo o tipo de serviços suportados pela equipe (e como), sistemas relacionados, exemplos.
• Uma breve descrição de alguns dos serviços mais importantes suportados pela equipe. Esta seção também destaca as principais tecnologias e os desafios de usá-las, os benefícios do envolvimento da SRE e suas responsabilidades.
• Principais princípios e valores da equipe.
• Links para o site e a documentação da equipe.

Também pressupõe a presença de uma declaração de visão (o conceito de visão para o futuro - uma descrição inspiradora dos objetivos de longo prazo da equipe) e um roteiro para vários blocos.

Documentação para integrar novos SREs

Investir em ferramentas e materiais de treinamento para novos funcionários afeta positivamente a velocidade de integração dos funcionários nos processos de trabalho. É benéfico para as equipes de SRE treinar os recém-chegados com todas as habilidades necessárias para trabalhar em turnos o mais rápido possível. A história de Zoe mostra claramente como a falta de treinamento em tempo integral para um novo funcionário faz de um incidente menor um mau funcionamento.

Muitas equipes de SRE preparam novos funcionários para os turnos usando listas de verificação. Uma lista de verificação de turnos geralmente abrange áreas de alto nível (divididas em subseções) que os membros da equipe devem entender. Exemplos dessas áreas são conceitos de produção, front-end e back-end, automação e instrumentação, monitoramento e registro. Além disso, as instruções para a preparação do turno e as tarefas executadas durante o turno podem ser incluídas na lista de verificação.

Para preparar novos membros da equipe do SRE, eles também usam exercícios de interpretação de papéis (chamados de Roda do infortúnio - a Roda do fracasso no Google). Este exercício é um cenário de falha com um conjunto específico de dados e sinais que, provavelmente, o SRE pode precisar resolver um problema durante um turno. Os membros da equipe se revezam no papel de um engenheiro de plantão para aprimorar seu domínio da recuperação de desastres e a capacidade de depurar o sistema. O Wheel of Misfortune verifica se cada membro da equipe sabe onde encontrar a documentação para corrigir o problema e como lidar com a falha.

Gerenciamento de armazenamento

Todas as informações da equipe do SRE podem ser espalhadas por vários sites, o repositório local e as pastas do Google Drive, o que complica bastante a pesquisa pela correta. Como aconteceu no exemplo descrito anteriormente, a ferramenta operacional crítica e as instruções para seu uso não estavam disponíveis para Zoe (SRE de plantão), pois estavam ocultas no diretório pessoal de seu líder técnico e a incapacidade de encontrá-los aumentou significativamente a duração da falha do serviço. Para se livrar de tais problemas, é necessário estruturar todas as informações e garantir que os membros da equipe saibam onde encontrá-las e armazená-las e como mantê-las. A estrutura bem desenvolvida ajudará a equipe a encontrar informações mais rapidamente. Os novos membros da equipe serão mais rápidos em manter-se atualizados, enquanto os engenheiros de serviço resolverão os problemas mais rapidamente.

Aqui estão algumas diretrizes sobre como criar e manter um repositório de documentação:

• Identifique os principais interessados ​​e realize entrevistas curtas para identificar todas as necessidades.
• Encontre o máximo de documentação possível e analise as lacunas no conteúdo.
• Baseie a estrutura do site para criar nova documentação nos lugares certos.
• Mova a documentação existente para um novo local.
• Arquive e retire a documentação antiga.
• Realize verificações regulares para garantir a qualidade / consistência da documentação suportada.
• Verifique se as consultas de pesquisa padrão retornam os documentos necessários no topo da lista de resultados da pesquisa.
• Use sinais, como o Google Analytics, para medir práticas padrão.

Nota sobre o suporte ao repositório: é importante verificar e atualizar regularmente a documentação. O nome do proprietário e a data da última verificação devem estar visíveis - essas informações ajudam a verificar a precisão do documento selecionado. Zoe na história conseguiu encontrar apenas documentação desatualizada de uma ferramenta crítica, perdendo a capacidade de resolver rapidamente o problema. A documentação não confiável e desatualizada torna o SRE menos eficiente, o que afeta negativamente a confiabilidade dos serviços gerenciados.

Disponibilidade do Repositório

As equipes do SRE devem garantir que a documentação permaneça disponível, mesmo se o repositório padrão falhar e não estiver disponível. Cada SRE do Google possui uma cópia de sua documentação crítica. Esta cópia está disponível em um dispositivo de armazenamento compacto criptografado ou em outro meio físico removível, porém seguro, semelhante a todo SRE em serviço.

Documentação para encerrar um serviço

Quando o ciclo de vida de um serviço terminar, o SRE o desativará de maneira previsível. Esta seção fornece recomendações para documentação sobre como colocar um serviço fora de serviço.

É importante notificar os usuários com antecedência sobre a desativação do serviço e fornecer um cronograma e etapas. Seu anúncio deve explicar quando o registro de novos usuários termina, como os bugs existentes e detectados no futuro serão processados ​​e quando o serviço finalmente parará de funcionar. Identifique claramente todas as datas importantes e o processo de redução do suporte ao SRE, envie anúncios intermediários à medida que avança.

Uma distribuição simples de e-mail não é suficiente - você precisa atualizar a página principal de documentação, playbooks e codelabs. Além disso, se possível, comente os arquivos de cabeçalho. Descreva os detalhes do anúncio em um documento (além da carta) ao qual os usuários podem se referir. A carta deve ser o mais curta possível, mas ao mesmo tempo informativa, refletindo todos os pontos principais. Descreva detalhes adicionais: motivação comercial para desativar o serviço, quais ferramentas os usuários podem usar para migrar para outro serviço, qual suporte está disponível durante a migração. Também vale a pena criar uma página de Perguntas frequentes, preenchendo-a com o tempo com novas informações sobre perguntas feitas pelos usuários.

O papel dos editores de documentação técnica

Editores técnicos (ou redatores técnicos) fornecem serviços que tornam a SRE mais eficiente e produtiva. O intervalo de tarefas não se limita à gravação de documentos separados, de acordo com os requisitos especificados pela equipe do SRE.

Aqui estão algumas recomendações práticas para editores técnicos sobre o trabalho com equipes de SRE.

• Os editores técnicos colaboram com o SRE para criar documentação operacional para serviços em execução e documentação de produção para produtos e ferramentas SRE.
• Eles criam e atualizam repositórios de documentação, estruturam e reorganizam de acordo com as necessidades dos usuários, e aprimoram documentos individuais como parte do gerenciamento geral do repositório.
• Os editores ajudam a identificar as melhorias exigidas pelo gerenciamento de documentação e informações. Isso inclui avaliar a documentação para coletar requisitos, melhorar documentos e sites criados por engenheiros, aconselhar as equipes sobre as regras para criar, organizar, redesenhar, pesquisar e manter a documentação.
• Os editores devem avaliar e aprimorar as ferramentas de documentação para fornecer melhores soluções de SRE.

Padrões

Os editores técnicos também fornecem modelos que simplificam a criação e o uso da documentação do SRE. Os modelos fazem o seguinte:

• Simplifique a criação da documentação, fornecendo aos engenheiros uma estrutura clara para a criação de novos documentos.
• Adicione seções de todos os documentos necessários para a conclusão completa da documentação.
• Eles ajudam o leitor a entender rapidamente o tópico do documento, o tipo de informação e como ele é organizado.

A Engenharia de confiabilidade do site contém vários modelos de documentação de amostra. Nesta seção, daremos mais alguns exemplos para mostrar como os modelos fornecem uma estrutura e um guia para os engenheiros preencherem com o conteúdo.

Entrevista de Serviço

Revisão

O que é isso O que ele esta fazendo? Alto nível descreve a funcionalidade fornecida aos clientes (usuário final, componentes, etc.).

Arquitetura

Explique como a arquitetura funciona. Descreva a movimentação de dados entre componentes. Considere adicionar um diagrama do sistema de dependência crítica e consultas e dados de fluxo.

Clientes e Dependências

Liste todos os clientes (pertencentes a outras equipes) que dependem dele e todos os serviços (pertencentes a outras equipes) dos quais dependem. (Isso também pode ser demonstrado na forma de um diagrama do sistema.)

Código e Configuração

Explique a estrutura da produção. Para onde ele está funcionando? Liste binários, tarefas, centros de dados e configurações do arquivo de configuração ou indique onde estão todos localizados. Forneça também o local do código e, se necessário, informações sobre a compilação.

Liste e descreva os arquivos de configuração, alterações e portas necessárias para operar este produto ou serviço.

Descreva o seguinte: quais arquivos de configuração foram alterados para este produto ou serviço? Como é feita a instalação?

Os processos

Descreva o seguinte: Quais daemons e outros processos devem estar em execução para o serviço funcionar? Quais scripts de controle foram criados para gerenciar o serviço?

Impressão

Listar e descrever os arquivos de log criados pelo componente e quais observações são feitas. Descreva o seguinte: Quais logs são gerados por este componente? O que há em cada arquivo? Quais são as recomendações para o estudo desses arquivos? Quais aspectos do componente devem ser monitorados para uma operação de serviço confiável?

Painéis e ferramentas

Cole links para painéis e ferramentas relacionados.

Poder

Indique o poder de uma única instância; Datacenter globalmente: QPS, largura de banda e valores de latência.

SLA

Forneça metas de acessibilidade.

Procedimentos padrão

Adicione links a procedimentos, incluindo teste de carga, atualizações / estados push / flag e assim por diante. Adicione links para documentação de alertas no manual de alertas.

Referências

Adicione links à documentação do projeto para o componente ou componentes relacionados, geralmente escritos pela equipe de desenvolvimento, bem como outras informações relacionadas.

Playbook

Título

No nome, especifique o nome do alerta (por exemplo, NormalAlert_AlertVery Very Normal).

Revisão

Descreva o seguinte: O que esse alerta significa? Ele chega a um pager ou apenas ao correio? Quais fatores desencadeiam um alerta? Quais partes do serviço são afetadas? Quais alertas estão associados a ele? Quem precisa ser notificado?

Alertas de nível de perigo

Justifique o grau de perigo da notificação e o impacto das partes afetadas nas condições gerais do serviço.

Confirmação

Forneça instruções claras para verificar e validar o status.

Solução de problemas

Listar e descrever métodos de depuração e fontes de informações relacionadas. Não se esqueça dos links para os painéis correspondentes. Ative alertas. Descreva o seguinte: O que aparecerá nos logs quando um alerta for acionado? Quais manipuladores de depuração existem? Existem scripts e comandos úteis? Que saída eles geram? Existem tarefas adicionais que precisam ser resolvidas após a eliminação do alerta?

Solução

Descreva e liste todas as soluções possíveis para o problema que está causando o alerta. Descreva o seguinte: Como soluciono o problema e resolvo o alerta? Quais comandos executar para reiniciar? Quem deve ser notificado se um alerta for acionado devido a ações do usuário? Quem tem experiência na depuração de um problema semelhante?

Escalada

Listar e descrever caminhos de escalação. Indique a pessoa ou equipe a ser notificada e quando fazê-lo. Se a escalação não for necessária - escreva sobre isso.

Links relacionados

Forneça links para alertas, procedimentos e documentação de revisão relacionados.
Relatório de Serviço Trimestral
1. Introdução
Descreva o serviço pelo qual a equipe é responsável.

Planejamento de capacidade

Incluindo:

• Demanda real pelo serviço, começando nos últimos 6 a 8 trimestres, expressa nas métricas mais relevantes para o serviço (por exemplo, QPS ou DAU).
• Previsão para os próximos 8 trimestres.
• Plano de capacidade que atenda à demanda projetada no nível de redundância necessário - especifique os riscos de déficit e / ou planejamento de capacidade.

Também recomendamos adicionar previsões para os últimos 2 a 4 trimestres, para que o leitor possa avaliar a estabilidade e a precisão das previsões.

Implementação / disponibilidade de SLA

Todos os serviços suportados pelo SRE devem ter um SLA escrito, que avalie o desempenho de cada trimestre.

A seção SLA deve conter os parâmetros dos principais componentes do serviço para medir a viabilidade trimestral das condições do SLA, bem como um link para uma equipe escrita do SLA.

Incidentes Concomitantes (Opcional)

Liste 3-5 incidentes ou falhas importantes por trimestre.

Conquistas (Opcional)

Liste as principais realizações do trimestre.

Alterações de SLA (desejadas)

Alterações recentes no SLA.

Detalhes do Serviço (Desejável)

A seção pode incluir crescimento, estatísticas de atrasos, etc.

Informações da equipe (opcional)

Pode incluir informações sobre a composição da equipe, status, projetos e estatísticas de turnos.

Fontes de dados (obrigatório)

Descreva as fontes usadas para obter valores de acessibilidade, métodos de cálculo, forneça links para os painéis correspondentes.

Team Charter

Quem somos

Em uma frase (~ 1 linha), descreva o ambiente tecnológico, as propostas dos clientes e da equipe, bem como o grau de envolvimento da SRE e conhecimentos especiais.

Serviços suportados

Para esclarecer melhor o escopo do trabalho, descreva os serviços (ou o grupo) que a equipe oferece suporte.

Como gastamos tempo

O escopo ajuda a criar um roteiro e a alcançar e apoiar objetivos de longo prazo.

Valores da equipe

Descreva claramente os valores. Isso afeta a maneira como os membros da equipe interagem entre si e como sua equipe é percebida pelos outros.

Conclusão

Independentemente de você ser um SRE, um gerente do SRE ou um editor técnico, agora você entende a importância crítica da documentação na vida de uma equipe eficaz do SRE. Uma boa documentação permite que a equipe de SRE cresça e adote uma metodologia clara para gerenciar serviços novos e existentes.

Assim, publicamos a parte final deste artigo, a primeira e a segunda partes podem ser lidas clicando nos hiperlinks, e você pode obter informações ainda mais úteis em nossa lição aberta , que será realizada em 19 de fevereiro. Estamos esperando por todos!