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:
time=2026-11-12T08:16:33.990+07:00 level=INFO msg=metrics addr=127.0.0.1:7452En el servidor, pídele las cifras principales:
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:
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"} 0Las 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, etiquetaop:add,remove,status,revoke,sync_pull): peticiones respondidas;sync_pullcuenta los streams de kolo-sync que otros peers abren sobre un log alojado: un lector nuevo abre dos (cabecera y luego pull), yFetchHeadyFetchabren uno cada uno.kolo_pin_refused_total(counter, etiquetareason: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, etiquetaop: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, etiquetasversion,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:
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:
ssh -L 7452:127.0.0.1:7452 user@203.0.113.10Mientras 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=:
[Service]
Environment=KOLO_PIN_METRICS=127.0.0.1:7452Usa off como valor para desactivar el endpoint. Después recarga y
reinicia:
sudo systemctl daemon-reload
sudo systemctl restart kolo-pinjournalctl -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:
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
Addha devueltopin: 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 == 0cubre un peer parado o un túnel cerrado, yabsent(...)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
- Prepara el propio peer: Ejecuta un peer de anclaje en un VPS.
- Lee la página de kolo-pin: su API, sus límites y sus errores.
- Consulta todos los valores por defecto en Límites.