Un manual de ejecución mensual para un informe de backlinks

Por qué mensual y no diario

Nuestro gráfico se actualiza aproximadamente una vez al mes. Un trabajo diario devuelve los mismos números.

Ejecutarlo con más frecuencia no hace que un informe sea más actual, solo lo hace más caro de explicar. Un lector que vea 30 puntos idénticos asumirá que la tubería está rota.

Elige un día cada mes deliberadamente, idealmente una semana después de que se asiente la actualización anterior. Escribe la fecha en el nombre del archivo, para que la programación en sí misma quede documentada.

Elige el calendario primero y deja que el informe lo siga. Un informe que se reconstruye cada vez que alguien abre el cuaderno no tiene una fecha clara en absoluto, y eso es difícil de defender en una revisión.

Qué almacenar además de los números

La mitad del informe es metadatos, así que almacénalos junto con los números.

Escribe la fecha de recuperación, el nombre de la acción, los parámetros (per, sort, order) y el campo de créditos de la respuesta en un pequeño archivo auxiliar junto a cada captura instantánea. Seis meses después, cuando un colega pregunte por qué octubre se ve diferente a septiembre, ese archivo responderá en diez segundos en lugar de una tarde.

Añade el commit de git del script y las versiones de los paquetes desde renv. Un informe que no puede decir qué código y qué estado del índice produjeron un gráfico es una captura de pantalla, no un análisis, sin importar lo ordenado que parezca el tibble.

Una estructura mínima de targets

Tres targets son suficientes cuando el plan se mantiene pequeño.

Un target recupera de la API y escribe el archivo con fecha, uno lee el archivo y construye el tibble, uno renderiza el documento Quarto. Como solo el primer target toca la red, puedes volver a ejecutar los otros sin conexión tantas veces como quieras y el gráfico nunca cambiará por accidente.

Fija las versiones de los paquetes con renv, registra la información de la sesión en el pie del informe, y mantén la tabla de umbrales desde la página de puntuación masiva en el repositorio junto al código. Para el lado del dinero, la página de presupuesto te dice cuánto debería costar un mes.

Cuando algo falla, lee el código primero. HTTP 401 significa que la clave es incorrecta o falta. HTTP 402 significa que se acabaron los créditos. Cualquier otra cosa merece ser registrada por completo. El desmontaje cubre esas etapas, y el ejemplo de unión es un buen primer trabajo para programar.

Aprender que una ejecución falló antes que un colega

Un informe de backlinks reproducible que falla silenciosamente engaña más que uno que nunca se ejecutó. La verdadera pregunta no es si el trabajo puede fallar, sino qué tan rápido alguien se entera.

Haz que el trabajo falle ruidosamente

Un trabajo programado sale con un estado distinto de cero cuando una llamada devuelve HTTP 401 o 402, y el programador marca la ejecución como fallida. Esa es la alerta más barata que tienes, y no necesita ningún servicio adicional.

Las recuperaciones parciales son el caso peligroso. Si el script escribe su archivo después de veinte de treinta fragmentos, el archivo existe y parece bien. Escribe en un nombre temporal y renómbralo solo en caso de éxito.

Envía un mensaje por fallo

Elige un canal para las fallas, como un correo electrónico al propietario del informe o un mensaje en el chat del equipo. Dos canales significan dos lugares donde buscar, y una mayor probabilidad de que nadie mire en ninguno.

El mensaje debe nombrar el target que falló, el código de estado y la hora. Todo lo demás pertenece al registro.

Verifica que el resultado sea plausible

Una ejecución puede tener éxito y aún así estar equivocada. Compara el recuento de filas con el del mes anterior, y marca una caída más allá de un umbral que elegiste de antemano.

La verificación puede ser tan simple como un rango esperado. El objetivo es notar una captura instantánea a medio llenar antes de que un gráfico llegue a un cliente.

Nombra un único propietario para el informe

Nombra un único propietario para el informe. Una alerta sin propietario es leída por todos y no actuada por nadie.

El propietario no tiene que arreglar el trabajo. El propietario tiene que decidir si un informe tardío es aceptable, y decirlo en el propio informe.

Escribe el nombre del propietario en la cabecera del manual de ejecución, y actualízalo cuando cambie el propietario. Un manual de ejecución con un propietario anterior es un peligro silencioso.

Elegir el día y ejecutar el primer trabajo a mano

La temporización y la primera ejecución deciden si la programación se mantiene. Ambas son fáciles de hacer mal en el primer mes, y ambas son baratas de hacer bien.

Dos decisiones, escritas una vez, ahorran la mayoría de los argumentos más tarde. La primera es el día. La segunda es dónde se ejecuta el temporizador. Ambas pertenecen al manual de ejecución, no en la cabeza de nadie.

Elige un día y escríbelo

Un día fijo en el mes, como el primer día laborable después de que se asiente la actualización, es más fácil de explicar que una suposición a principios de mes.

Pon el día en el archivo de programación mismo, para que la temporización sea parte del código y no un recuerdo en el calendario de alguien.

Ejecuta el primer trabajo a mano

La primera ejecución programada debe ser manual. Ejecuta el script tú mismo, lee el registro, compara el archivo con el anterior, y solo entonces entrega el temporizador.

La primera ejecución también prueba el almacén de secretos. Una clave que funciona en tu máquina pero falta en CI es una razón común para el primer fallo programado.

Mantén el archivo auxiliar honesto

El archivo auxiliar registra lo que hizo la ejecución. Si una persona lo escribe a mano, se desvía de la ejecución. Haz que el script lo escriba, y permite que las personas solo lo lean.

Un archivo auxiliar que el script nunca tocó es una nota, no un registro, y el informe debe citar el registro.

Compara el archivo auxiliar con el archivo una vez al mes. Si los números en los dos discrepan, la ejecución falló de una manera que el script no notó.

Dónde vive el temporizador

Un ejecutor alojado y una entrada cron local fallan de maneras diferentes. Un ejecutor alojado puede ser pausado por su propia configuración, y una entrada cron local se detiene cuando la máquina está en suspensión. Verifica cuál elegiste, y prueba el temporizador una vez con una programación corta antes de la real.

Cualquiera que elijas, escribe el temporizador en el repositorio junto al script, para que la siguiente persona sepa dónde vive el trabajo.