# ghchronicle

ghchronicle es una herramienta de código abierto que recoge todas las métricas que GitHub expone sobre una cuenta y guarda cada una con la fecha en que ocurrió.

Source: https://docs.jmrp.io/ghchronicle/es/

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

## Lo que recoge

- [95 medidas](https://docs.jmrp.io/ghchronicle/es/collectors/measurements/)
- [34 colectores](https://docs.jmrp.io/ghchronicle/es/collectors/)
- [11 destinos](https://docs.jmrp.io/ghchronicle/es/sinks/)
- [154 paneles de dashboard](https://docs.jmrp.io/ghchronicle/es/dashboards/)

## 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, y ninguno de hace más de treinta días. Las notificaciones de la bandeja se conservan tres meses salvo que se guarden. Los logs de los jobs se borran por omisión 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 único binario estático de Go, sin dependencias en tiempo de ejecución.

## 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: un relleno recorre estrellas, pull requests y ejecuciones hasta donde la API responda, pero el tráfico de más de catorce días, los eventos más allá de los últimos trescientos o de hace más de treinta días y los logs más antiguos que el periodo de retención del repositorio, noventa días por omisión, no los tiene nadie
- 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.

```sh
go install github.com/jmrplens/ghchronicle/v2/cmd/ghchronicle@latest
```

### Configurar

La configuración mínima que hace algo. Un ${VAR} en una credencial, una dirección o una ruta se lee del entorno, así que este fichero no guarda secretos.

```yaml
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.

```text
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 hora y las claves de la cuenta una vez al día.
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**: Todo salvo el exportador de Prometheus se envía por push: a InfluxDB, PostgreSQL, Graphite, Elasticsearch, Prometheus por su receptor OTLP, 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ápido](https://docs.jmrp.io/ghchronicle/es/start/quickstart/): De cero a la primera pasada.
- [El token](https://docs.jmrp.io/ghchronicle/es/start/token/): Qué permisos, y por qué el automático no basta.
- [La fecha del punto](https://docs.jmrp.io/ghchronicle/es/how/dating/): La idea de la que se deriva el resto del diseño.
- [Elegir almacén](https://docs.jmrp.io/ghchronicle/es/sinks/): Qué puede y qué no puede responder cada uno de los 11.