kolo docsbeta

Monitorizar un peer de anclaje

Lee las métricas de un peer de anclaje de kolo-pin con Prometheus, mantén el endpoint en privado y recibe una alerta antes de que se llene su almacenamiento.

En esta página

El comando kolo-pin sirve métricas en el formato de texto de Prometheus. Te dicen cuánto se ha llenado el peer de anclaje, cuánto trabajo tiene y por qué rechaza peticiones. Esta página parte del peer de Ejecuta un peer de anclaje en un VPS.

El endpoint de métricas

kolo-pin run responde a GET /metrics en 127.0.0.1:7452 por defecto. El flag es -metrics y su variable de entorno es KOLO_PIN_METRICS; el flag gana a la variable. Ponlo a off para desactivar el endpoint. Escucha aparte del endpoint de salud, GET /healthz en 127.0.0.1:7451.

La dirección es una dirección TCP, solo IPv4. Una dirección IPv6 se rechaza y kolo-pin sale con el código 2. Al arrancar, kolo-pin registra en el log dónde escucha:

Texto
time=2026-11-12T08:16:33.990+07:00 level=INFO msg=metrics addr=127.0.0.1:7452

En el servidor, pídele las cifras principales:

bash
curl -s http://127.0.0.1:7452/metrics | grep -E '^kolo_pin_(bytes|disk|owners|logs|entries|requests)'

Esto es lo que imprimió justo después de que un propietario anclara un log de cuatro entradas:

Texto
kolo_pin_bytes_max 1e+11
kolo_pin_bytes_received_total 2040
kolo_pin_bytes_served_total 0
kolo_pin_bytes_used 3081
kolo_pin_disk_free_bytes 1.73485133824e+11
kolo_pin_entries 4
kolo_pin_logs 1
kolo_pin_owners 1
kolo_pin_requests_total{op="add"} 1
kolo_pin_requests_total{op="remove"} 0
kolo_pin_requests_total{op="revoke"} 0
kolo_pin_requests_total{op="status"} 1
kolo_pin_requests_total{op="sync_pull"} 0

Las métricas de almacenamiento y de peticiones aparecen cuando el almacén ya está abierto, más o menos con la línea serving del log. Los contadores vuelven a 0 cada vez que kolo-pin arranca.

Un programa en Go que ejecuta la propia biblioteca obtiene las mismas métricas kolo_pin_* si pasa un prometheus.Registerer en Options.Metrics, y las sirve como quiera.

Las métricas

  • kolo_pin_bytes_used (gauge): bytes guardados para todos los propietarios, claves y valores.
  • kolo_pin_bytes_max (gauge): el límite -max-bytes.
  • kolo_pin_disk_free_bytes (gauge): bytes libres en el sistema de archivos de la carpeta de datos, solo en Linux, macOS y Windows.
  • kolo_pin_owners (gauge): propietarios con una capability en uso o un log alojado.
  • kolo_pin_logs (gauge): logs alojados.
  • kolo_pin_entries (gauge): entradas de todos los logs alojados.
  • kolo_pin_requests_total (counter, etiqueta op: add, remove, status, revoke, sync_pull): peticiones respondidas; sync_pull cuenta los streams de kolo-sync que otros peers abren sobre un log alojado: un lector nuevo abre dos (cabecera y luego pull), y FetchHead y Fetch abren uno cada uno.
  • kolo_pin_refused_total (counter, etiqueta reason: bad_token, expired_token, replayed_token, revoked, quota_exceeded, disk_full, oversized_entry, bad_signature, bad_proof, other): peticiones rechazadas.
  • kolo_pin_delete_markers_applied_total (counter): marcas de borrado del propietario aplicadas; cada una elimina un texto cifrado que el peer tenía. Una entrada que llega ya borrada no se cuenta.
  • kolo_pin_bytes_received_total (counter): bytes de entradas nuevas (registros y textos cifrados) obtenidos por pull de los propietarios y guardados.
  • kolo_pin_bytes_served_total (counter): bytes que kolo-sync escribió a los peers que hacen pull de logs alojados, con todas las tramas.
  • kolo_pin_active_connections (gauge): conexiones de kolo-secure abiertas.
  • kolo_pin_active_sync_streams (gauge): streams de kolo-sync en marcha ahora, los que se sirven a peers que hacen pull más los pulls desde los propietarios.
  • kolo_pin_active_pulls (gauge): de esos, los pulls desde los propietarios en marcha ahora.
  • kolo_pin_sync_pull_duration_seconds (histogram): cuánto tarda cada pull desde un propietario.
  • kolo_pin_request_duration_seconds (histogram, etiqueta op: add, remove, status, revoke): cuánto tarda cada petición de anclaje. Los streams de kolo-sync (sync_pull) no se cronometran, así que esa etiqueta no aparece aquí.
  • kolo_pin_build_info (gauge, etiquetas version, go_version): siempre 1; las etiquetas indican la compilación.
  • kolo_pin_uptime_seconds (gauge): segundos desde que arrancó el programa.

Los dos histogramas usan cubetas de 0,01, 0,05, 0,1, 0,5, 1, 5, 10, 30, 60 y 300 segundos. Cada valor de op y de reason existe desde el principio, a 0, así que una alerta ve el primer rechazo. El comando también exporta las métricas estándar go_* del runtime, y las métricas process_* en Linux y Windows.

Qué revelan las métricas

Muestran totales de todo el peer: bytes, propietarios, logs, entradas, recuentos de peticiones y de rechazos por tipo, duraciones y la compilación.

Nunca contienen una clave de propietario, un ID de log, una clave de peer, una dirección IP ni ninguna cifra de un solo propietario. Las etiquetas solo toman los valores fijos de la lista de arriba, así que nada de lo que envía un peer se convierte nunca en una etiqueta.

Aun así, los totales cuentan algo. Quien lea el endpoint sabrá cuántos propietarios y logs alojas, cuánto guardas y con qué frecuencia y por qué se rechazan peticiones. Mantenlo en privado. Los logs de kolo-pin contienen más (claves públicas, IDs de log, direcciones), como explica Ejecuta un peer de anclaje en un VPS.

Recoge las métricas con Prometheus

Si Prometheus se ejecuta en el VPS, apúntalo a la dirección de loopback. Este prometheus.yml consulta kolo-pin cada 30 segundos y carga las reglas de alerta que verás más abajo:

prometheus.yml
rule_files:
  - kolo-pin-rules.yml

scrape_configs:
  - job_name: kolo-pin
    scrape_interval: 30s
    static_configs:
      - targets: ["127.0.0.1:7452"]

Si Prometheus se ejecuta en tu propio ordenador, abre un túnel SSH al VPS en lugar de abrir un puerto:

Terminal
ssh -L 7452:127.0.0.1:7452 user@203.0.113.10

Mientras el túnel está abierto, la misma configuración funciona en tu ordenador, porque allí 127.0.0.1:7452 lleva ahora al VPS. Cuando el túnel se cierra, las consultas fallan y salta la última alerta de abajo.

Configúralo en systemd

Por defecto ya escucha en 127.0.0.1:7452. Para dejarlo explícito o para cambiarlo, añade esta línea a la sección [Service] de la unidad de la guía del VPS, junto a las otras líneas Environment=:

/etc/systemd/system/kolo-pin.service
[Service]
Environment=KOLO_PIN_METRICS=127.0.0.1:7452

Usa off como valor para desactivar el endpoint. Después recarga y reinicia:

bash
sudo systemctl daemon-reload
sudo systemctl restart kolo-pin

journalctl -u kolo-pin muestra la línea metrics con la dirección.

Reglas de alerta

Tres reglas en formato de Prometheus, para el archivo kolo-pin-rules.yml que carga la configuración de arriba:

kolo-pin-rules.yml
groups:
  - name: kolo-pin
    rules:
      - alert: KoloPinStorageAlmostFull
        expr: kolo_pin_bytes_used / kolo_pin_bytes_max > 0.9
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "kolo-pin on {{ $labels.instance }} uses over 90% of -max-bytes"
      - alert: KoloPinRefusingDiskFull
        expr: increase(kolo_pin_refused_total{reason="disk_full"}[10m]) > 0
        labels:
          severity: critical
        annotations:
          summary: "kolo-pin on {{ $labels.instance }} refuses new data: disk full"
      - alert: KoloPinNoMetrics
        expr: up{job="kolo-pin"} == 0 or absent(kolo_pin_bytes_used{job="kolo-pin"})
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "No kolo-pin metrics for 5 minutes"
  • La primera salta cuando el peer lleva 15 minutos usando el 90 % de -max-bytes. Sube -max-bytes (si el disco tiene sitio) o haz una lista de tus propietarios.
  • La segunda salta cuando Add ha devuelto pin: pinning peer disk full (ErrDiskFull) al menos una vez en los últimos 10 minutos: los propietarios ya no pueden añadir datos nuevos.
  • La tercera salta cuando ninguna consulta ha funcionado en 5 minutos. up == 0 cubre un peer parado o un túnel cerrado, y absent(...) cubre un objetivo que falta o que responde sin las métricas de kolo-pin.

-max-bytes cuenta las claves y los valores guardados, no los bloques del disco, así que el disco real puede llenarse antes. Vigila también kolo_pin_disk_free_bytes.

Mantenlo fuera de la dirección pública

kolo-pin nunca escucha métricas en una dirección pública a menos que tú se la des. El endpoint no tiene autenticación ni TLS.

Qué no se ha probado

Todo lo que respalda esta página se ejecutó en un solo ordenador, en 127.0.0.1: la compilación, kolo-pin run con las direcciones por defecto, curl de /healthz y /metrics antes y después de que el programa del propietario de la guía del VPS anclara un log, -metrics off y el rechazo de IPv6. No se han probado Prometheus, la configuración de recogida ni las reglas de alerta (solo se ha comprobado que son YAML válido), el túnel SSH, la unidad de systemd, un proxy inverso ni un servidor Linux.

Siguientes pasos