Cadencias

Cada familia de métricas de GitHub se recoge con su propio intervalo, y el bloque every es donde se cambian esos intervalos.

every:
  default: 15m
  groups:
    ci: 1m
    feeds: 10m
  families:
    actions: 30s

Las tres capas

Gana la más específica. La entrada de una familia gana a la de su grupo, la de un grupo gana a default, y default gana al valor interno. Lo que se omite cae a la capa de abajo, así que un fichero que solo tenga families: se comporta exactamente como siempre. El valor es una duración de Go: 30s, 15m, 2h, 36h.

Capa	Alcanza	Se escribe
every.families	una familia	families: {keys: 24h}
every.groups	todas las familias de un grupo	groups: {ci: 1m}
every.default	todas las que no nombren las dos de arriba	default: 15m
la tabla interna	todas las que no nombre ninguna capa	nada

Son tres claves de un bloque anidado y no tres claves planas porque un mapa plano no puede con este vocabulario. security y account son a la vez nombre de familia y nombre de grupo, así que every: {security: 1m} tiene dos lecturas y ninguna forma de elegir entre ellas. Bajo families: la palabra es la familia; bajo groups: es el grupo; ya no queda sitio donde plantear la duda. Ese mismo anidamiento es lo que hace seguras las palabras default y groups: son campos de una estructura fija, y una clave desconocida se rechaza al arrancar, así que ninguna familia puede tapar una capa ni ninguna capa una familia.

Las dos capas amplias nunca encienden una familia

default y groups no alcanzan a una familia cuya cadencia interna es 0. deps, history y joblogs vienen apagadas y se activan nombrándolas bajo families: y de ninguna otra forma. Solo deps son 1,8 MB de SBOM por repositorio, y un default escrito para acelerar las familias rápidas no debe encender además tres familias que nunca mencionaste. Es la misma regla que ya sigue groups.

Del revés sale la forma más corta de recoger poco: apagarlo todo con default y luego nombrar lo que quieres de vuelta.

every:
  default: 0
  families:
    traffic: 6h
    actions: 15m

Cada familia, su grupo y su cadencia interna

Los valores internos no son números redondos elegidos por prolijidad. Salieron de una auditoría con sus costes, y el motivo de cada uno vive junto al número en el código. Esa es la fuente, y esta tabla está anclada a ella: un test de internal/config compara cada grupo, cada duración y cada motivo de aquí abajo con el código en ambos sentidos, así que una familia que se añada, se mueva o cambie de coste sin que esta tabla la siga rompe la compilación. ghchronicle -groups imprime esa misma pertenencia.

Grupo	Familia	Por omisión	Motivo
account	account	1h	el calendario de contribuciones se mueve con cada contribución y los contadores del perfil con cada seguimiento y cada estrella, y una pasada es un punto de GraphQL y siete peticiones REST, de las que solo se cobra la del perfil: GitHub casi nunca la respondió con un 304, una vez en 48 lecturas condicionales, y los seis listados de paquetes lo responden hasta que cambia un paquete
account	achievements	1h	las insignias de la página pública del perfil, que ninguna API lista, y lo que le falta a cada una con niveles para el siguiente; una pasada transfiere la página, 36 KB y fuera del presupuesto, y las pull requests fusionadas desde el día anterior por dos puntos de GraphQL, así que un nivel alcanzado por la tarde se ve por la tarde, y el historial entero se recorre una vez por semana, 24 MB
account	billing	1h	el mes en curso se mueve mientras corre la integración continua: había cambiado en cada una de las 46 lecturas cada seis horas medidas, y una pasada son dos peticiones, ese mes y el anterior, de las que solo se cobra la primera
account	history	0	apagada hasta que se la nombre: recorre cada año pasado y lo que va de este, y las filas son idempotentes
account	keys	24h	una clave SSH o GPG cambia cuando alguien la cambia, y lo que importa es su fecha de caducidad, no la hora en que se vio
account	outbound	1h	las estrellas dadas, el trabajo en repositorios ajenos y las respuestas aceptadas allí, por unos nueve puntos de GraphQL por pasada, así que la hora no cuesta nada que se note y una respuesta aceptada esta tarde está en el panel esta tarde
account	profile	12h	paquetes, gists y cuentas sociales, todo ello editado a mano
account	totals	1h	los números de toda la vida se mueven con cada estrella, fork, fusión y push, y una pasada es un punto de GraphQL por la cuenta, uno por cada diez repositorios y uno por cada veinticinco archivados que se dejan fuera, y una petición del presupuesto de búsqueda
audience	forks	12h	la lista entera cabe en una página, y un fork es un suceso raro
audience	stars	1h	una estrella puede llegar a cualquier hora, y tras el único recorrido completo de la lista una pasada es un punto de GraphQL por cada diez repositorios para las cien más nuevas y una petición condicional por repositorio para el historial diario, que respondió un 304 gratis a 184 de las 185 medidas
audience	traffic	6h	la ventana de catorce días se reescribe entera cada vez, así que una pasada perdida se repara en la siguiente
ci	actions	15m	una ejecución de workflow termina en minutos, y su tiempo en cola solo merece verse mientras ocurre
ci	artifacts	1h	los artefactos aparecen con la ejecución que los hizo y caducan en escala de días
ci	deployments	30m	es la superficie que lee un dashboard de entrega, y la página más nueva es un punto de GraphQL por cada cinco repositorios, que trajo hasta cuatro filas nuevas por pasada medida, así que la media hora cuesta poco
ci	joblogs	0	apagada hasta que se la nombre: es texto y no una medida, cuesta una petición por fallo, y solo tiene sentido con un almacén de logs conectado
collector	ratelimit	15m	es gratis, y merece la pena tenerla a la resolución de la familia más rápida
feeds	activity	15m	el log del repositorio guarda cien entradas, que cubrieron veintiséis horas en el repositorio más activo medido, y una pasada son una o dos peticiones condicionales por repositorio, que respondieron un 304 gratis a 2.320 de las 2.356 medidas
feeds	events	15m	una petición core por pasada, y el feed se había movido en 43 de las 46 medias horas medidas, así que el cuarto de hora es lo pronto que un evento llega al panel; la ventana, los últimos trescientos eventos de los últimos treinta días, es mucho más ancha que eso
feeds	notifs	15m	una petición core por pasada y veinte una vez al día por la bandeja entera, y un hilo muestra solo su último movimiento, así que un movimiento que otro adelanta antes de la siguiente lectura no se ve nunca; la mitad de las pasadas medidas trajo una fila nueva
repos	branches	24h	las ramas se crean y se borran todo el día, pero lo que responde la fila es cuáles están rancias ahora mismo, que es una pregunta diaria
repos	deps	0	apagada hasta que se la nombre: el SBOM son 1,8 MB por repositorio y tiene su propio presupuesto de cien por minuto
repos	inventory	24h	cuatro peticiones core por repositorio, para ajustes que cambian solo cuando alguien los cambia
repos	policyfiles	24h	SECURITY.md, CODEOWNERS, dependabot.yml y FUNDING.yml se mueven una vez por trimestre
repos	repo	1h	estrellas, forks, lenguajes y temas se mueven despacio, y una pasada son tres peticiones REST por repositorio, casi todas un 304 gratis, y dos puntos de GraphQL por cada diez repositorios
repos	rulesets	24h	un ruleset se edita unas pocas veces al año y cada versión conserva su propia fecha; las dos peticiones responden un 304 gratis hasta que alguien edita uno, también en la primera pasada tras un reinicio, porque la caché de ETag se guarda junto al fichero de estado
repos	settings	6h	webhooks, rulesets, entornos y claves de despliegue cambian solo cuando alguien los cambia
security	analyses	1h	GitHub poda los análisis de code scanning y cada push analizado añade alguno, y una pasada es una petición condicional por repositorio con code scanning, tres de ellas cobradas en la pasada mediana medida, con las negativas del resto recordadas un día
security	security	1h	una alerta es algo sobre lo que actuar hoy, y la lista de abiertas es corta
work	commits	1h	un punto de GraphQL por cada repositorio cuya rama por defecto tiene un commit de las dos últimas cadencias, que tenían 38 de 999 respuestas medidas, y uno por cada veinticinco repositorios, compartido con issues e issueevents, para preguntar cuáles, así que la hora es lo pronto que se ve en el panel un push
work	discussions	1h	una discusión se responde en horas o días y pocos repositorios tienen foro, y una pasada son dos puntos de GraphQL por cada uno que lo tiene y nada por el resto
work	issueevents	1h	la cronología de lo que se movió en dos cadencias, un punto GraphQL por cada repositorio donde se movió una issue o una pull request y nada por los demás, así que la hora es lo pronto que merece verse una transición
work	issues	1h	uno o dos puntos GraphQL por cada repositorio cuyas issues o pull requests se movieron en dos cadencias, nada por los demás, y una vez al día un punto o más por sus elementos abiertos y hasta cuatro por página de lo que se movió en el día, así que la hora es lo pronto que se ve en el panel una revisión o una fusión
work	planning	6h	etiquetas e hitos se editan a mano, unas pocas veces por semana como mucho
work	stats	12h	GitHub las recalcula despacio de todas formas, así que preguntar más a menudo devuelve los mismos números

El aviso cuando una cadencia va más rápido de lo que el valor merece

Una capa amplia es una forma barata de ralentizarlo todo y una forma cara de acelerarlo todo. default: 15m le pide a GitHub las claves SSH de la cuenta noventa y seis veces al día para un valor que cambia dos veces al año, y una cadencia de grupo hace lo mismo un nivel más abajo: work contiene familias que la auditoría midió en 1h y en 12h, así que un número ahí es un número sobre seis respuestas distintas.

Por eso cada familia que una configuración recoge cuatro veces más a menudo o más que su cadencia interna se nombra al arrancar, con la clave que la fijó, los dos números, y el motivo de que ese número sea el que es:

level=WARN msg="every.default sets keys to 15m against a built-in 24h, 96 times
  more often: an SSH or GPG key changes when somebody changes it, and what
  matters is its expiry date, not the hour it was noticed"
level=WARN msg="every.groups.work sets stats to 1h against a built-in 12h, 12
  times more often: GitHub recomputes these slowly anyway, so asking more often
  returns the same numbers"

Es un aviso y nunca un rechazo, y es siempre por familia, nunca por grupo. Una línea que dijese “el grupo work va demasiado rápido” no nombraría nada sobre lo que actuar: el motivo de que una cadencia sea la que es pertenece a la familia, así que el aviso también.

Cuatro es el umbral porque los valores internos están sobre una escalera, 15m 30m 1h 2h 6h 12h 24h, y el mayor salto entre dos peldaños vecinos es de tres, de 2h a 6h. Ninguna familia viene a 2h desde que discussions pasó a la hora, pero el peldaño sigue siendo donde cae un paso abajo desde 6h. Cuatro es por tanto el menor factor que ningún peldaño suelto alcanza. Bajar un peldaño es un ajuste deliberado de quien está mirando esa familia y se queda callado; cuatro o más solo puede ser una capa amplia cayendo donde nunca se la eligió, o un número escrito sin leer esta tabla.

Nada avisa por ir más despacio. Esto va de desperdicio, no de gusto.

Grupos: recoger menos que todo

every fija cada cuánto corre una familia. groups fija qué familias existen de verdad para esta instalación. Si se omite la clave, recoge para todos los grupos, que es el valor por defecto y lo que “cada métrica que GitHub expone” ha significado siempre.

groups: [audience, account, repos, security]

Nombrar cualquier grupo apaga los demás: sus familias no se piden nunca y sus medidas no se escriben nunca. ghchronicle -groups imprime la lista, que es:

Grupo	Familias
audience	forks, stars, traffic
account	account, achievements, billing, history, keys, outbound, profile, totals
repos	branches, deps, inventory, policyfiles, repo, rulesets, settings
work	commits, discussions, issueevents, issues, planning, stats
ci	actions, artifacts, deployments, joblogs
security	analyses, security
feeds	activity, events, notifs
collector	ratelimit

El groups de primer nivel y every.groups son dos preguntas distintas sobre los mismos ocho nombres: la primera decide si un grupo llega a recogerse, la segunda cada cuánto. Una cadencia bajo every.groups para un grupo que el groups de primer nivel deja fuera es legal y avisa, en lugar de fallar: estrechar una instalación no debería obligar además a podar un bloque every que ajustaste el año pasado.

Los dos ejes tienen que decir que sí, y solo uno de ellos puede decir que no. Un grupo que no se nombra apaga sus familias diga lo que diga every, y nombrar un grupo nunca resucita una familia cuya cadencia es cero. En eso consiste que una familia venga apagada mientras el valor por defecto es todo.

Escribir groups: [] se rechaza en lugar de leerse como “no recojas nada”: omitir la clave es la forma de pedirlo todo, así que una lista vacía solo puede ser un error.

Lo que GitHub borra no se puede recuperar después, se haga lo que se haga, y está en tres grupos distintos: el feed de eventos, que guarda trescientos eventos y ninguno de hace más de treinta días, y la bandeja, que conserva las notificaciones tres meses salvo las guardadas (feeds); la ventana de catorce días del tráfico (audience); y los logs de los jobs, que se borran al acabar el periodo de retención del repositorio, noventa días por omisión, y con ellos, desde el 1 de octubre de 2026, las propias ejecuciones de workflows (ci). Lo que GitHub borró antes de que ghchronicle lo leyera no existe en ninguna parte. Todo lo demás se puede rellenar luego con -backfill.

Los paneles de un grupo apagado darán error

Una medida que no se escribe nunca no existe como tabla, e InfluxDB 3 responde con un error, y no con cero filas, a una consulta que nombra una tabla que no tiene. Los dashboards se generan una vez, para el conjunto completo de métricas, así que cada panel alimentado por un grupo apagado muestra ese error. Es lo esperado. Son una demostración de lo que el colector sabe dibujar, no una vista que se reorganice según tu configuración. PostgreSQL y Elasticsearch se comportan igual; Prometheus y Graphite no tienen esquema que echar en falta, así que esos mismos paneles leen No data.

Las secciones de los dashboards tampoco están alineadas con los grupos, así que un grupo apagado vacía algunos paneles de varias secciones en lugar de una sección entera. Stars and forks lee gh_repo de repos además de gh_star y gh_star_day de audience; Code lee gh_workflow_run de ci y gh_repo_activity de feeds junto a sus propios commits; Inventory lee de repos y de account, y sus paneles de licencias leen gh_dependency_license, que es la familia deps y viene apagada se seleccione repos o no.

Qué significa 0

0 apaga todas las familias que alcance la capa en la que está escrito. No es “tan a menudo como se pueda” ni “usa el valor por defecto”: esas familias no corren nunca, no escriben nada y no cuestan nada.

every:
  families:
    billing: 0 # nada de datos de facturación
    artifacts: 0 # nada de filas de artefactos

Tres familias vienen apagadas y se activan dándoles cualquier duración, bajo families: y en ningún otro sitio:

• joblogs es la cola del log de cada job fallido. Es texto y no una medida, cuesta una petición por fallo, y solo tiene sentido con un almacén de logs conectado. El destino de InfluxDB lo excluye por omisión.
• history recorre el calendario de contribuciones de cada año pasado, un punto de GraphQL por año, hasta el día en que se creó la cuenta, y el año en curso de enero a hoy. Los años pasados no cambian y las filas son idempotentes; la fila del año en curso es una instantánea marcada partial, así que una cadencia diaria la mantiene al día y una única pasada la deja congelada en el día en que corrió.
• deps es el grafo de dependencias. El SBOM son 1,8 MB por repositorio y tiene su propio presupuesto de cien por minuto.

Una configuración que no deja nada activado lo dice al arrancar, en vez de correr un bucle vacío en silencio.

Un nombre desconocido es fatal al arrancar

every.families.trafic: unknown collector (known: account, achievements, actions, activity, ...)
every.families.feeds: "feeds" is a group, not a family; every.groups.feeds is where a whole group's cadence lives
every.groups.actions: "actions" is a family, not a group; it is in group "ci", and every.families.actions is where its cadence lives

Cada nombre se comprueba contra los colectores conocidos y los grupos conocidos antes de la primera llamada a la API. De lo contrario, una errata significaría una familia corriendo en silencio con su valor por defecto para siempre, y a un nombre escrito en la capa equivocada se le dice en qué capa iba.

heartbeat: el tic del bucle, que no es una cadencia

heartbeat fuerza cada cuánto despierta el bucle de pasadas a preguntar qué familias tocan. No le da intervalo a ninguna familia, no se compara con nada de la tabla de arriba, y no se gana ninguno de los avisos de esta página.

heartbeat: 15s

Si se omite, el bucle late a la cadencia más corta configurada, entre un minuto y una hora, que es lo que quiere una instalación real: una familia que corre cada cuarto de hora no se retrasa por otra que corre cada doce horas. El techo importa en una configuración cuyas cadencias son todas más lentas que una hora: la búsqueda de la más corta arranca en una hora, así que el bucle sigue despertando cada hora y no encuentra nada que hacer. Se pone cuando lo que quieres bajo control es el bucle en sí, que casi siempre es una pasada de prueba. Es la única forma de hacer girar el bucle más rápido que ese suelo de un minuto, porque el suelo existe para sobrevivir a una cadencia mal tecleada y un heartbeat explícito no lo es.

Una familia toca en el primer tic en que su cadencia ha pasado, con medio tic de margen. El bucle lee el reloj unos milisegundos después de despertar, en una cantidad que cambia de un tic a otro, y sin ese margen una familia cuya cadencia es un número entero de tics esperaba un tic de más la mitad de las veces: hasta la 2.6.0, que trajo la corrección escrita para la 2.5.2, las familias de cuarto de hora corrían cada 24 minutos de media y las horarias cada 69. Medio tic absorbe eso y nunca deja correr a una familia un tic antes de tiempo.

Un heartbeat más largo que la cadencia más corta frena a esa familia, y el arranque lo dice:

level=WARN msg="heartbeat is 1h and the shortest cadence is 15m (actions), so
  no family can run more often than every 1h"

Las familias lentas se turnan

El servicio en marcha arranca una familia de cadencia de seis horas o más en cada pasada, o las menos que aún mantienen todas las cadencias cuando una no basta (más abajo), y deja cualquier otra que toque para el tic siguiente.

Las familias que corren en la misma pasada quedan marcadas con el mismo instante en el fichero de estado, así que vuelven a tocar juntas en cada cadencia, para siempre. Un grupo así se forma siempre que se marcan muchas familias a la vez: una instalación nueva, un -once o un backfill antes del servicio, una familia que se enciende. Hasta la 2.6.0 las ocho familias diarias de la cuenta de producción corrían en la primera pasada del día UTC, todos los días, y sus cinco familias de doce horas juntas en una pasada propia. El 2026-09-26 la pasada diaria gastó 294 peticiones core facturables y 24,3 MB frente a 17,5 peticiones de la pasada mediana, y con la de doce horas 45 minutos después, su hora fue ocho veces la hora mediana en peticiones core. Las puso ahí el calendario, no el trabajo.

La familia que arranca es la que lleva más tiempo tocando, contado desde lo más reciente entre su última pasada y la última vez que el proceso la dejó arrancar. La segunda mitad importa para una familia cuyas pasadas fallan todas: una pasada fallida no se marca como hecha, así que por su última pasada sola sería la familia más atrasada en cada pasada y se quedaría con todos los turnos. Contada así, se pone detrás de las demás.

Una familia espera a cada una de las otras como mucho una vez, así que la peor espera es un tic por cada otra familia lenta, y solo la última de un grupo recién formado espera tanto. Con el tic de cuarto de hora que dan las cadencias internas:

Calendario	Familias de 6h o más	Espera más larga
las cadencias internas	11	10 tics, 2h30m
con deps e history a 24h	13	12 tics, 3h
con deps, history y joblogs a un día	14	13 tics, 3h15m

Esa espera se paga una vez. En cuanto dos familias han corrido en pasadas distintas, tocan en pasadas distintas y nada vuelve a juntarlas: una semana simulada de las trece, todas pendientes en una misma pasada al principio, tuvo cada familia arrancando exactamente una cadencia después de su arranque anterior desde el primer día.

El log dice qué familia arrancó y cuáles esperan, así que una familia lenta que falta en una pasada en la que tocaba queda explicada:

level=INFO msg="slow families due together take turns" starting=planning
  waiting=settings,traffic,forks,profile,stats,branches,inventory,keys,policyfiles,rulesets

Una por pasada vale mientras puede cumplir todas las cadencias, y una configuración con un tic más largo puede tener más familias lentas que eso. every.default: 6h late cada hora, porque nada en ella corre más a menudo, con treinta y una familias a seis horas, y una por pasada arrancaría cada una cada treinta y una horas. Ahí una pasada arranca las menos que caben, seis, y ninguna familia espera tanto como su cadencia.

Solo el servicio se turna. -once corre todas las familias que tocan, porque no tiene un tic siguiente al que dejar ninguna: lanzado una vez al día por un planificador, la dejaría para el día siguiente. Un backfill, una tarjeta y la primera pasada de un servicio que ceba el exportador de Prometheus corren todas las familias diga lo que diga el fichero de estado. La pasada cebada anota después solo las familias a las que les tocaba, así que un reinicio no vuelve a poner las demás en un mismo instante, y cada una conserva el turno que tenía.

Hacerlas más lentas

Si el presupuesto que se queda corto es core, alarga artifacts y después actions, los dos mayores costes REST, que crecen con lo activos que estén los repositorios. Si es graphql, alarga issues, issueevents y commits, que leen solo los repositorios donde algo se movió y por eso cuestan más cuantos más se muevan. No son los únicos que siguen a la actividad y no al tamaño: activity solo se cobra por un repositorio cuyo log se movió, y outbound cuesta un punto más por cada centenar adicional de lo que lee. Ver qué crece con la actividad, no con el tamaño.

El síntoma de unas cadencias demasiado rápidas es un aviso en cada pasada:

level=WARN msg="rate limit reserve reached, family skipped" family=actions

Cadencia no es resolución

Alargar una cadencia no hace más gruesa la historia, porque los puntos se fechan por la cosa que ocurrió y no por la pasada. Recoger las ejecuciones de workflows cada hora en vez de cada quince minutos sigue registrando cada ejecución en el segundo en que terminó. Lo que arriesga una cadencia larga es perder una ventana entera: events lee los últimos trescientos eventos, notifs solo el último movimiento de cada hilo y activity las últimas cien entradas del log de cada repositorio, así que lo que salga de una de ellas entre dos pasadas se pierde.