Por qué es importante la documentación de SRE. Parte 3

Buenas tardes a todos! Tenemos prisa por compartir la noticia de que en febrero estamos lanzando una nueva transmisión en el curso Devops - Prácticas y herramientas , lo que significa que es hora de terminar lo que comenzamos y publicar la tercera parte del artículo: "Por qué es importante la documentación de SRE" . Vamos!

Documentos para administrar comandos SRE

Los equipos de SRE necesitan documentación confiable y asequible para trabajar de manera eficiente.

Sitio del equipo

Nota: en lugar del sitio, puede usar un espacio o sección por separado en Confluence / Wiki.

El sitio del equipo es importante porque proporciona coordinación de información y documentación relacionada con el equipo SRE y sus proyectos. Por ejemplo, en Google, muchos equipos de SRE usan g3doc (una plataforma interna de documentación de Google donde los muelles viven en código fuente con el código asociado), y algunos equipos usan g3doc y Google Sites: en este caso, las páginas de g3doc están estrechamente relacionadas con el código / detalles de implementación.

Carta del equipo



Los equipos de SRE deben apoyar una carta publicada que describa la motivación laboral y documente la participación continua. El estatuto es necesario para establecer la identidad, los objetivos principales y el valor del equipo en toda la empresa.

La carta suele tener los siguientes elementos:

• Una descripción de alto nivel del área de responsabilidad del equipo. Incluyendo el tipo de servicios soportados por el equipo (y cómo), sistemas relacionados, ejemplos.
• Una breve descripción de algunos de los servicios más importantes respaldados por el equipo. Esta sección también destaca las tecnologías clave y los desafíos de su uso, los beneficios de involucrar a SRE y sus responsabilidades.
• Principios y valores clave del equipo.
• Enlaces al sitio web del equipo y documentación.

También supone la presencia de una declaración de visión (el concepto de visión para el futuro, una descripción inspiradora de los objetivos a largo plazo del equipo) y una hoja de ruta para varios bloques.

Documentación para integrar nuevas SRE

Invertir en herramientas y materiales de capacitación para nuevos empleados tiene un efecto positivo en la velocidad de integración de los empleados en los procesos de trabajo. Es beneficioso para los equipos de SRE capacitar a los recién llegados con todas las habilidades de trabajo por turnos necesarias lo antes posible. La historia de Zoe muestra claramente cómo la falta de capacitación a tiempo completo para un nuevo empleado hace que un incidente menor sea un mal funcionamiento grave.

Muchos equipos de SRE preparan nuevos empleados para turnos utilizando listas de verificación. Una lista de verificación de turnos generalmente cubre áreas de alto nivel (divididas en subsecciones) que los miembros del equipo deben entender. Ejemplos de tales áreas son los conceptos de producción, front-end y back-end, automatización e instrumentación, monitoreo y registro. Además, las instrucciones para prepararse para el turno y las tareas realizadas durante el turno pueden incluirse en la lista de verificación.

Para preparar a los nuevos miembros del equipo de SRE, también usan ejercicios de juego de roles (se les llama Rueda de la desgracia, la Rueda del fracaso en Google). Este ejercicio es un escenario de falla con un conjunto específico de datos y señales que SRE podría necesitar hipotéticamente para resolver un problema durante un turno. Los miembros del equipo se turnan para desempeñar el papel de un ingeniero de turno para perfeccionar su dominio de la recuperación ante desastres y la capacidad de depurar el sistema. Wheel of Misfortune verifica si cada miembro del equipo sabe dónde encontrar la documentación para solucionar el problema y cómo lidiar con la falla.

Gestión de almacenamiento

Toda la información del equipo SRE puede estar dispersa en varios sitios, el repositorio local y las carpetas de Google Drive, lo que complica enormemente la búsqueda del correcto. Como sucedió en el ejemplo descrito anteriormente, la herramienta operativa crítica y las instrucciones para su uso no estaban disponibles para Zoe (SRE en servicio), ya que estaban ocultas en el directorio personal de su líder técnico, y la imposibilidad de encontrarlas aumentó significativamente la duración de la falla del servicio. Para deshacerse de tales problemas, debe estructurar toda la información y asegurarse de que los miembros del equipo sepan dónde encontrarla y almacenarla, y cómo mantenerla. La estructura bien desarrollada ayudará al equipo a encontrar información más rápido. Los nuevos miembros del equipo serán más rápidos para mantenerse actualizados, mientras que los ingenieros en servicio resolverán los problemas más rápido.

Aquí hay algunas pautas sobre cómo crear y mantener un repositorio de documentación:

• Identifique a las partes interesadas clave y realice entrevistas cortas para identificar todas las necesidades.
• Encuentre tanta documentación como sea posible y analice los vacíos en el contenido.
• Base la estructura de su sitio para crear nueva documentación en los lugares correctos.
• Mover la documentación existente a una nueva ubicación.
• Archive y elimine la documentación anterior.
• Realice comprobaciones periódicas para garantizar la calidad / coherencia de la documentación admitida.
• Asegúrese de que las consultas de búsqueda estándar devuelvan los documentos necesarios en la parte superior de la lista de resultados de búsqueda.
• Use señales, como Google Analytics, para medir las prácticas estándar.

Nota sobre el soporte del repositorio: es importante verificar y actualizar regularmente la documentación. El nombre del propietario y la fecha de la última verificación deben estar visibles: esta información ayuda a verificar la precisión del documento seleccionado. En la historia, Zoe solo pudo encontrar documentación obsoleta de una herramienta crítica, perdiendo así la capacidad de resolver rápidamente el problema. La documentación poco confiable y desactualizada hace que SRE sea menos eficiente, lo que afecta negativamente la confiabilidad de los servicios administrados.

Disponibilidad del repositorio

Los equipos de SRE deben asegurarse de que la documentación permanezca disponible incluso si el repositorio estándar falla y no está disponible. Cada Google SRE posee una copia de su documentación crítica. Esta copia está disponible en un dispositivo de almacenamiento compacto cifrado o en algún medio físico extraíble pero seguro similar que cada SRE tiene en servicio.

Documentación para desmantelar un servicio

Cuando finaliza el ciclo de vida de un servicio, el SRE lo desmantelará de manera predecible. Esta sección proporciona recomendaciones para la documentación sobre cómo dejar un servicio fuera de servicio.

Es importante notificar a los usuarios antes del desmantelamiento del servicio y proporcionar un cronograma y pasos. Su anuncio debe explicar cuándo finaliza el registro de nuevos usuarios, cómo se procesarán los errores existentes y detectados en el futuro, y cuándo el servicio finalmente dejará de funcionar. Identifique claramente todas las fechas importantes y el proceso de reducir el soporte para SRE, envíe anuncios provisionales a medida que avanza.

Una distribución simple de correo electrónico no es suficiente: debe actualizar la página principal de documentación, libros de jugadas y codelabs. Además, si es posible, comente los archivos de encabezado. Describa los detalles del anuncio en un documento (además de la carta) que los usuarios puedan consultar. La carta debe ser lo más breve posible, pero al mismo tiempo informativa, reflejando todos los puntos principales. Describa detalles adicionales: motivación empresarial para desactivar el servicio, qué herramientas pueden usar los usuarios para migrar a otro servicio, qué soporte está disponible durante la migración. También vale la pena crear una página de preguntas frecuentes, llenándola con el tiempo con nueva información sobre las preguntas formuladas por los usuarios.

El papel de los editores de documentación técnica.

Los editores técnicos (o escritores técnicos) proporcionan servicios que hacen que SRE sea más eficiente y productivo. El rango de tareas no se limita a escribir documentos separados de acuerdo con los requisitos especificados por el equipo de SRE.

Aquí hay algunas recomendaciones prácticas para editores técnicos sobre cómo trabajar con equipos de SRE.

• Los editores técnicos colaboran con SRE para crear documentación operativa para ejecutar servicios y documentación de producción para productos y herramientas SRE.
• Crean y actualizan los repositorios de documentación, los estructuran y los reorganizan de acuerdo con las necesidades de los usuarios, y mejoran los documentos individuales como parte de la gestión general del repositorio.
• Los editores ayudan a identificar las mejoras requeridas por la documentación y la gestión de la información. Esto incluye evaluar la documentación para recopilar requisitos, mejorar los documentos y sitios creados por ingenieros, asesorar a los equipos sobre las reglas para crear, organizar, rediseñar, buscar y mantener la documentación.
• Los editores deben evaluar y mejorar las herramientas de documentación para proporcionar mejores soluciones SRE.

Patrones

Los editores técnicos también proporcionan plantillas que simplifican la creación y el uso de la documentación de SRE. Las plantillas hacen lo siguiente:

• Simplifique la creación de documentación proporcionando a los ingenieros una estructura clara para crear nuevos documentos.
• Agregue secciones de todos los documentos necesarios para completar completamente la documentación.
• Ayudan al lector a comprender rápidamente el tema del documento, el tipo de información y cómo está organizado.

Site Reliability Engineering contiene varias plantillas de documentación de muestra. En esta sección, daremos algunos ejemplos más para mostrar cómo las plantillas proporcionan una estructura y una guía para que los ingenieros completen el contenido.

Entrevista de servicio

Revisar

Que es esto Que esta haciendo el Alto nivel describe la funcionalidad proporcionada a los clientes (usuario final, componentes, etc.).

Arquitectura

Explicar cómo funciona la arquitectura. Describa el movimiento de datos entre componentes. Considere agregar un diagrama de sistema de dependencia crítico y consultas y datos de flujo.

Clientes y dependencias

Enumere todos los clientes (que pertenecen a otros equipos) que dependen de él y todos los servicios (que pertenecen a otros equipos) de los que depende. (Esto también se puede demostrar en forma de diagrama del sistema).

Código y configuración

Explicar la estructura de producción. A donde esta corriendo? Enumere los archivos binarios, el trabajo, los centros de datos y la configuración del archivo de configuración, o indique dónde están ubicados. También proporcione la ubicación del código y, si es necesario, información sobre la compilación.

Enumere y describa los archivos de configuración, los cambios y los puertos necesarios para operar este producto o servicio.

Describa lo siguiente: ¿qué archivos de configuración se han cambiado para este producto o servicio? ¿Cómo se realiza la configuración?

Los procesos

Describa lo siguiente: ¿Qué demonios y otros procesos deben ejecutarse para que el servicio funcione? ¿Qué scripts de control se crearon para administrar el servicio?

Pie de imprenta

Enumere y describa los archivos de registro creados por el componente y qué observaciones se realizan. Describa lo siguiente: ¿Qué registros genera este componente? ¿Qué hay en cada archivo? ¿Cuáles son las recomendaciones para estudiar estos archivos? ¿Qué aspectos del componente deben ser monitoreados para una operación de servicio confiable?

Tableros y herramientas

Pegue enlaces a paneles y herramientas relacionadas.

Poder

Indicar el poder de una sola instancia; Centro de datos a nivel mundial: QPS, ancho de banda y valores de latencia.

SLA

Proporcionar objetivos de accesibilidad.

Procedimientos estándar

Agregue enlaces a los procedimientos, incluidas las pruebas de carga, las actualizaciones / los estados push / flag, etc. Agregue enlaces a la documentación de alertas en el libro de jugadas de alertas.

Referencias

Agregue enlaces a la documentación de diseño para el componente o componentes relacionados, generalmente escritos por el equipo de desarrollo, así como otra información relacionada.

Libro de jugadas

Titulo

En el nombre, especifique el nombre de la alerta (por ejemplo, NormalAlert_AlertVery Very Normal).

Revisar

Describa lo siguiente: ¿Qué significa esta alerta? ¿Se trata de un buscapersonas o solo por correo? ¿Qué factores desencadenan una alerta? ¿Qué partes del servicio están afectadas? ¿Qué alertas están asociadas con él? ¿Quién necesita ser notificado?

Alertas de nivel de peligro

Justifique el grado de peligro de la notificación y el impacto de las partes afectadas en el estado general del servicio.

Confirmación

Proporcione instrucciones claras para verificar y validar el estado.

Solución de problemas

Enumerar y describir métodos de depuración y fuentes de información relacionadas. No te olvides de los enlaces a los paneles correspondientes. Activa las alertas. Describa lo siguiente: ¿Qué aparecerá en los registros cuando se active una alerta? ¿Qué controladores de depuración hay? ¿Hay scripts y comandos útiles? ¿Qué salida generan? ¿Hay alguna tarea adicional que deba resolverse después de la eliminación de la alerta?

Solución

Describa y enumere todas las posibles soluciones al problema que causa la alerta. Describa lo siguiente: ¿Cómo soluciono el problema y resuelvo la alerta? ¿Qué comandos ejecutar para reiniciar? ¿A quién se debe notificar si se activa una alerta debido a acciones del usuario? ¿Quién tiene experiencia en la depuración de un problema similar?

Escalada

Enumerar y describir las rutas de escalación. Indique a la persona o equipo que se notificará y cuándo hacerlo. Si la escalada no es necesaria, escriba al respecto.

Enlaces relacionados

Proporcione enlaces a alertas relacionadas, procedimientos y revise la documentación.
Informe de servicio trimestral
Introduccion
Describa el servicio del que es responsable el equipo.

Planificación de capacidad

Incluyendo:

• La demanda real del servicio, a partir de los últimos 6-8 trimestres, expresada en las métricas más relevantes para el servicio (por ejemplo, QPS o DAU).
• Pronóstico para los próximos 8 trimestres.
• Plan de capacidad que satisface la demanda proyectada en el nivel requerido de redundancia: especifique los riesgos de déficit y / o planificación de capacidad.

También recomendamos agregar pronósticos para los últimos 2-4 trimestres para que el lector pueda evaluar la estabilidad y precisión de los pronósticos.

Implementación / Disponibilidad de SLA

Todos los servicios respaldados por SRE deben tener un SLA escrito, que evalúa el desempeño de cada trimestre.

La sección SLA debe contener los parámetros de los componentes principales del servicio para medir la viabilidad trimestral de las condiciones SLA, así como un enlace a un equipo escrito de SLA.

Incidentes concomitantes (opcional)

Enumere 3-5 incidentes o fallas importantes por trimestre.

Logros (Opcional)

Enumere los principales logros del trimestre.

Cambios de SLA (deseado)

Cambios recientes a SLA.

Detalles del servicio (deseable)

La sección puede incluir crecimiento, estadísticas de demoras, etc.

Información del equipo (opcional)

Puede incluir información sobre la composición del equipo, estados, proyectos, estadísticas de turnos.

Fuentes de datos (obligatorio)

Describa las fuentes utilizadas para obtener valores de accesibilidad, métodos de cálculo, proporcione enlaces a los paneles correspondientes.

Carta del equipo

Quienes somos

En una oración (~ 1 línea) describa el entorno tecnológico, los clientes y las propuestas del equipo, así como el grado de participación en SRE y experiencia especial.

Servicios soportados

Para aclarar aún más el alcance del trabajo, describa los servicios (o su grupo) que el equipo admite.

Cómo pasamos el tiempo

El alcance ayuda a crear una hoja de ruta y a alcanzar y apoyar objetivos a largo plazo.

Valores del equipo

Describa claramente los valores. Esto afecta la forma en que los miembros del equipo interactúan entre sí y cómo los demás perciben a su equipo.

Conclusión

Independientemente de si usted es un SRE, o un gerente de SRE, o un editor técnico, ahora comprende la importancia crítica de la documentación en la vida de un equipo de SRE efectivo. La buena documentación permite al equipo de SRE crecer y adherirse a una metodología clara para administrar servicios nuevos y existentes.

Por lo tanto, publicamos la parte final de este artículo, la primera y la segunda parte se pueden leer haciendo clic en los hipervínculos, y puede obtener información aún más útil en nuestra lección abierta , que se realizará el 19 de febrero. ¡Estamos esperando a todos!