ghchronicle

91medidas

34colectores

10destinos

152paneles de dashboard

Cada una lleva la fecha en que ocurrió la cosa, que es lo que hace que una pregunta sobre julio pasado siga teniendo respuesta.

Qué es

GitHub responde la mayoría de las preguntas sobre el presente y casi ninguna sobre el pasado. La API de tráfico sirve catorce días y olvida. El feed de actividad guarda los últimos trescientos eventos, sean de cuando sean. Las notificaciones leídas desaparecen. Los logs de los jobs se borran a los noventa días.

ghchronicle recorre esas superficies con una cadencia y escribe cada observación como un punto fechado, en la base de datos que ya tengas. Un binario de Go, sin más dependencia que un analizador de YAML.

Para quién es

• Para quien ya tenga una base de datos de series temporales y un Grafana
• Para quien mantenga proyectos y quiera conservar tráfico y estrellas más allá de la ventana de GitHub
• Para equipos que quieran tiempos de fusión, carga de revisión y coste de CI como historia y no como un número que se reinicia
• Para quien quiera sacar sus datos de GitHub antes de que GitHub los descarte

Qué no es

• No es un servicio alojado: corre en tu máquina, con tu token
• No sustituye a GitHub Insights, que responde sobre el ahora
• No recupera lo que GitHub ya ha descartado: empieza el día que lo ejecutas
• No es un generador de insignias, aunque sepa dibujar una

Cómo se usa

Tres pasos, y la primera pasada aterriza en tu base de datos.

Instalar

Un binario, una release o la imagen de contenedor.

go install github.com/jmrplens/ghchronicle/cmd/ghchronicle@latest

Configurar

La configuración mínima que hace algo. Cada ${VAR} se lee del entorno, así que este fichero no guarda secretos.

github:
  token: ${GITHUB_TOKEN}
targets:
  user: your-login
sinks:
  influxdb:
    url: http://localhost:8181
    bucket: github

Recoger

Lo que aterriza en la base de datos. Fíjate en las marcas de tiempo: la estrella está fechada en 2024, no hoy, porque es cuando se dio.

gh_star,repo=parser,user=someone starred=1i 1731590400000000000
gh_traffic,repo=parser,kind=views count=142i,uniques=61i 1757376000000000000
gh_pull_request,repo=parser,number=318,state=MERGED churn=214i,seconds_to_merge=5820i 1757462400000000000

Cómo está hecho

Cuatro ideas, y la segunda es de la que se derivan las demás.

1. Recorrer

   Cada familia de métricas tiene su cadencia, porque se mueven a velocidades muy distintas: las ejecuciones de workflows cada cuarto de hora, el calendario de contribuciones cada doce.

2. Fechar

   Un punto lleva el momento en que ocurrió la cosa, no el momento en que se recogió. Eso es lo que hace que volver a recoger converja en lugar de acumular copias.

3. Enviar por push

   Aquí nada se recoge por scrape. Envía por push a InfluxDB, PostgreSQL, Graphite, Elasticsearch, Prometheus, OpenTelemetry, Loki, Telegraf, un fichero o cualquier cosa a la que llegue Telegraf, así que corre donde pueda alcanzarlos.

4. Dibujar

   Una especificación de dashboard, renderizada una vez por almacén. Los mismos paneles con la base de datos que elijas, y donde un almacén no puede responder con honestidad, el panel lo dice.

Por dónde empezar

Inicio rápidoDe cero a la primera pasada.El tokenQué permisos, y por qué el automático no basta.La fecha del puntoLa idea de la que se deriva el resto del diseño.Elegir almacénQué puede y qué no puede responder cada uno de los 10.