kolo docsbeta

Monitorar um peer de fixação

Leia as métricas de um peer de fixação da kolo-pin com o Prometheus, mantenha o endpoint privado e receba um alerta antes que o armazenamento encha.

Nesta página

O comando kolo-pin serve métricas no formato de texto do Prometheus. Elas mostram o quanto o peer de fixação está cheio, o quanto ele está ocupado e por que ele recusa requisições. Esta página parte do peer de Rode um peer de fixação em uma VPS.

O endpoint de métricas

kolo-pin run responde a GET /metrics em 127.0.0.1:7452 por padrão. A flag é -metrics e a variável de ambiente é KOLO_PIN_METRICS; a flag vence a variável. Use off para desligar o endpoint. Ele escuta separado do endpoint de health, GET /healthz em 127.0.0.1:7451.

O endereço é um endereço TCP, só IPv4. Um endereço IPv6 é recusado e a kolo-pin sai com o código 2. Ao iniciar, a kolo-pin registra no log onde está escutando:

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

No servidor, peça os números principais:

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

Foi isto que ele imprimiu logo depois que um dono fixou um log de quatro 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

As métricas de armazenamento e de requisições aparecem quando o armazenamento já está aberto, mais ou menos junto com a linha serving do log. Os contadores voltam a 0 toda vez que a kolo-pin inicia.

Um programa em Go que roda a própria biblioteca recebe as mesmas métricas kolo_pin_* passando um prometheus.Registerer em Options.Metrics, e as serve como quiser.

As métricas

  • kolo_pin_bytes_used (gauge): bytes guardados para todos os donos, chaves e valores.
  • kolo_pin_bytes_max (gauge): o limite -max-bytes.
  • kolo_pin_disk_free_bytes (gauge): bytes livres no sistema de arquivos da pasta de dados, só no Linux, no macOS e no Windows.
  • kolo_pin_owners (gauge): donos com uma capability em uso ou um log hospedado.
  • kolo_pin_logs (gauge): logs hospedados.
  • kolo_pin_entries (gauge): entradas de todos os logs hospedados.
  • kolo_pin_requests_total (counter, rótulo op: add, remove, status, revoke, sync_pull): requisições respondidas; sync_pull conta os streams da kolo-sync que outros peers abrem sobre um log hospedado: um leitor novo abre dois (cabeçalho e depois pull), e FetchHead e Fetch abrem um cada.
  • kolo_pin_refused_total (counter, rótulo reason: bad_token, expired_token, replayed_token, revoked, quota_exceeded, disk_full, oversized_entry, bad_signature, bad_proof, other): requisições recusadas.
  • kolo_pin_delete_markers_applied_total (counter): marcadores de exclusão do dono aplicados; cada um descarta um texto cifrado que o peer tinha. Uma entrada que chega já excluída não é contada.
  • kolo_pin_bytes_received_total (counter): bytes de entradas novas (registros e textos cifrados) puxados dos donos e guardados.
  • kolo_pin_bytes_served_total (counter): bytes que a kolo-sync escreveu para os peers que puxam logs hospedados, com todos os frames.
  • kolo_pin_active_connections (gauge): conexões da kolo-secure abertas.
  • kolo_pin_active_sync_streams (gauge): streams da kolo-sync rodando agora, os servidos a peers que puxam mais os pulls a partir dos donos.
  • kolo_pin_active_pulls (gauge): desses, os pulls a partir dos donos rodando agora.
  • kolo_pin_sync_pull_duration_seconds (histogram): quanto tempo leva cada pull a partir de um dono.
  • kolo_pin_request_duration_seconds (histogram, rótulo op: add, remove, status, revoke): quanto tempo leva cada requisição de fixação. Os streams da kolo-sync (sync_pull) não são cronometrados, então esse rótulo não aparece aqui.
  • kolo_pin_build_info (gauge, rótulos version, go_version): sempre 1; os rótulos identificam o build.
  • kolo_pin_uptime_seconds (gauge): segundos desde que o programa iniciou.

Os dois histogramas usam faixas de 0,01, 0,05, 0,1, 0,5, 1, 5, 10, 30, 60 e 300 segundos. Cada valor de op e de reason existe desde o início, em 0, então um alerta vê a primeira recusa. O comando também exporta as métricas padrão go_* do runtime, e as métricas process_* no Linux e no Windows.

O que as métricas revelam

Elas mostram totais do peer inteiro: bytes, donos, logs, entradas, contagens de requisições e de recusas por tipo, durações e o build.

Elas nunca contêm uma chave de dono, um ID de log, uma chave de peer, um endereço IP nem qualquer número de um único dono. Os rótulos só recebem os valores fixos da lista acima, então nada do que um peer envia vira um rótulo.

Mesmo assim, os totais contam alguma coisa. Quem lê o endpoint fica sabendo quantos donos e logs você hospeda, quanto você guarda e com que frequência e por que as requisições são recusadas. Mantenha o endpoint privado. Os logs da kolo-pin contêm mais (chaves públicas, IDs de log, endereços), como explica Rode um peer de fixação em uma VPS.

Colete as métricas com o Prometheus

Se o Prometheus roda na VPS, aponte-o para o endereço de loopback. Este prometheus.yml coleta a kolo-pin a cada 30 segundos e carrega as regras de alerta mais abaixo:

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"]

Se o Prometheus roda no seu próprio computador, abra um túnel SSH para a VPS em vez de abrir uma porta:

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

Enquanto o túnel está aberto, a mesma configuração funciona no seu computador, já que lá 127.0.0.1:7452 agora leva até a VPS. Quando o túnel fecha, as coletas falham e o último alerta abaixo dispara.

Configure no systemd

O padrão já escuta em 127.0.0.1:7452. Para deixar isso explícito, ou para mudar o endereço, adicione esta linha à seção [Service] da unit do guia da VPS, junto com as outras linhas Environment=:

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

Use off como valor para desligar o endpoint. Depois recarregue e reinicie:

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

journalctl -u kolo-pin mostra a linha metrics com o endereço.

Regras de alerta

Três regras no formato do Prometheus, para o arquivo kolo-pin-rules.yml que a configuração acima carrega:

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"
  • A primeira dispara quando o peer passa 15 minutos usando 90% de -max-bytes. Aumente -max-bytes (se o disco tiver espaço) ou liste os seus donos.
  • A segunda dispara quando Add retornou pin: pinning peer disk full (ErrDiskFull) pelo menos uma vez nos últimos 10 minutos: os donos não conseguem mais adicionar dados novos.
  • A terceira dispara quando nenhuma coleta funcionou por 5 minutos. up == 0 cobre um peer parado ou um túnel fechado, e absent(...) cobre um alvo que sumiu ou que responde sem as métricas da kolo-pin.

-max-bytes conta as chaves e os valores guardados, não os blocos do disco, então o disco real pode encher antes. Acompanhe também kolo_pin_disk_free_bytes.

Mantenha fora do endereço público

A kolo-pin nunca escuta métricas em um endereço público, a não ser que você passe um. O endpoint não tem autenticação nem TLS.

O que não foi testado

Tudo o que está por trás desta página rodou em um único computador, em 127.0.0.1: o build, kolo-pin run com os endereços padrão, curl de /healthz e /metrics antes e depois de o programa do dono do guia da VPS fixar um log, -metrics off e a recusa de IPv6. O Prometheus, a configuração de coleta e as regras de alerta (só foi conferido que são YAML válido), o túnel SSH, a unit do systemd, um proxy reverso e um servidor Linux não foram testados.

Próximos passos