# ghchronicle

Recoge todas las métricas que GitHub expone sobre una cuenta y las guarda con la fecha en que ocurrieron.

Source: https://jmrplens.github.io/ghchronicle/es/

Cada una 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

- [91 medidas](/ghchronicle/es/collectors/measurements/)
- [34 colectores](/ghchronicle/es/collectors/)
- [10 destinos](/ghchronicle/es/sinks/)
- [152 paneles de dashboard](/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, 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.

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

```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 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ápido](/ghchronicle/es/start/quickstart/): De cero a la primera pasada.
- [El token](/ghchronicle/es/start/token/): Qué permisos, y por qué el automático no basta.
- [La fecha del punto](/ghchronicle/es/how/dating/): La idea de la que se deriva el resto del diseño.
- [Elegir almacén](/ghchronicle/es/sinks/): Qué puede y qué no puede responder cada uno de los 10.