Prometheus & Grafana

Node64 liefert unter /api/metrics Kennzahlen im Textformat von Prometheus – vom Kern über Healthchecks, DynDNS, DNS64, PROXY64 und CDN64 bis zu den Zertifikaten. So bindest du deine Node in ein bestehendes Monitoring ein, baust Grafana-Dashboards und schreibst eigene Alarmregeln.

Überblick

Einrichten

1. Lege im Menüpunkt API (/api/docs, Abschnitt API-Keys) einen eigenen Key an, zum Beispiel mit dem Namen prometheus. Mehr dazu unter Lokale API.
2. Speichere den Key auf dem Prometheus-Server in einer Datei, etwa /etc/prometheus/node64.key. Die Datei enthält nur den Key (node64_…).
3. Trage einen Scrape-Job in die prometheus.yml ein und lade Prometheus neu.

scrape_configs:
  - job_name: node64
    scheme: https            # oder http, je nach Aufruf der Oberfläche
    metrics_path: /api/metrics
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/node64.key   # Inhalt: node64_...
    tls_config:
      insecure_skip_verify: true   # nur bei selbstsigniertem Zertifikat der Oberfläche
    static_configs:
      - targets: ["node64.lan:8080"]

Node64 spricht HTTP und HTTPS auf demselben Port. Hat die Oberfläche ein richtiges Zertifikat (siehe Zertifikate), lässt du insecure_skip_verify weg. Jede Node hat ihre eigenen API-Keys. Für mehrere Nodes legst du daher je Node einen eigenen Scrape-Job mit eigener Key-Datei an.

Test von Hand:

curl -s -H "Authorization: Bearer $(cat node64.key)" http://node64.lan:8080/api/metrics | head

Anmeldung und Schutz

• /api/metrics ist wie die übrige API geschützt: ohne Key kommt 401.
• Jede Abfrage setzt beim API-Key „zuletzt benutzt“ – du siehst also in der Key-Liste, ob Prometheus noch abfragt.
• Falsche Keys bremst Node64 wie bei der übrigen API aus (nach 5 Fehlversuchen nur noch ein Versuch alle 30 Sekunden).
• Nutze einen eigenen Key nur für Prometheus. Brauchst du ihn nicht mehr, löschst du ihn – ohne andere Skripte zu stören.

Alle Metriken

Zeitpunkte sind Unix-Zeit in Sekunden (Endung _seconds), Dauern in Sekunden, Datenmengen in Bytes. Werte mit „immer 1“ tragen ihre Information im Label – zählen lässt sich das mit count oder sum.

Kern

Healthchecks

Labels je Check: token (bleibt gleich, auch wenn sich der Name ändert), check (Name), type und group.

Proxmox VE

Je System (system), Node und Gast: node64_pve_up, node64_pve_error, node64_pve_poll_failures_total, node64_pve_quorate, node64_pve_guests_running, node64_pve_guests_bad, node64_pve_node_up, node64_pve_guest_state, node64_pve_guest_up sowie CPU, RAM und Disk als Anteil 0..1 (node64_pve_node_*_ratio, node64_pve_guest_*_ratio), je Gast dazu Netz und Disk-I/O in Byte/s (node64_pve_guest_net_*_bytes, node64_pve_guest_disk_*_bytes), RAM in Byte und CPUs (node64_pve_guest_memory_bytes, node64_pve_guest_cpus). Die vollständige Liste steht unter Proxmox VE.

Docker

Für die Docker-Überwachung. Je Host: node64_docker_up, node64_docker_enabled, node64_docker_poll_failures_total, node64_docker_last_poll_seconds, node64_docker_containers_running, node64_docker_containers_bad. Je Container: node64_docker_container_state{state,detail}, …_container_up, …_container_restarts, …_container_cpu_ratio, …_container_cpus, …_container_memory_ratio, …_container_memory_bytes, …_container_memory_limit_bytes, …_container_uptime_seconds, …_container_net_in_bytes, …_container_net_out_bytes, …_container_disk_read_bytes und …_container_disk_write_bytes.

DynDNS

DNS64

Die Zähler laufen seit dem letzten Start des DNS-Servers. Eine Änderung der Einstellungen startet ihn neu – rate() und increase() kommen damit zurecht.

PROXY64 und CDN64

Labels je Host: host_id (bleibt gleich), host (erster Name) und kind (proxy, redirect, dead, passthrough).

CDN64 – die Werte stammen aus dem letzten Abgleich der Node mit ipv64 (jede Minute):

Zertifikate

Die Werte der zentralen Zertifikatsverwaltung gehören zum Kern und sind immer dabei. Labels je Zertifikat: cert_id, name (erster Name) und source (ipv64, alias, http, dns, ca, self, upload).

Honeypot64

Nur bei eingeschaltetem Modul; Einzelheiten unter Honeypot64.

Beispiele für Alarmregeln

Diese Regeln kannst du direkt in eine Regeldatei von Prometheus übernehmen und an Alertmanager weiterleiten. Passe Schwellen und Wartezeiten (for) an deine Umgebung an.

groups:
  - name: node64
    rules:
      - alert: Node64Down
        expr: up{job="node64"} == 0
        for: 5m
        annotations:
          summary: "Node64 {{ $labels.instance }} antwortet nicht"
      - alert: Node64ModuleError
        expr: node64_module_error == 1
        for: 10m
        annotations:
          summary: "Modul {{ $labels.module }} meldet einen Fehler"
      - alert: Node64CheckDown
        expr: node64_hc_check_up == 0 and on(token) node64_hc_check_maintenance == 0
        for: 2m
        annotations:
          summary: "{{ $labels.check }} ist gestört"
      - alert: Node64CertExpiresSoon
        expr: node64_hc_check_cert_expiry_seconds - time() < 14 * 86400
        annotations:
          summary: "Zertifikat von {{ $labels.check }} läuft in unter 14 Tagen ab"
      - alert: Node64DynDNSError
        expr: node64_dyndns_target_ok == 0
        for: 15m
      - alert: Node64DNSUpstreamDown
        expr: node64_dns64_upstream_up == 0
        for: 5m
      - alert: Node64CertExpires
        expr: node64_cert_expiry_seconds - time() < 14 * 86400 and on(cert_id) node64_cert_auto_renew == 1
        annotations:
          summary: "Zertifikat {{ $labels.name }} läuft in unter 14 Tagen ab (Erneuerung klappt nicht?)"
      - alert: Node64CDN64TargetDown
        expr: node64_cdn64_host_target_up == 0 and on(host_id) node64_cdn64_host_enabled == 1
        for: 5m
      - alert: Node64CDN64TunnelDown
        expr: node64_cdn64_online_edge_connected == 0
        for: 3m
      - alert: Node64IPv64Disconnected
        expr: node64_link_linked == 1 and node64_link_connected == 0
        for: 10m

Grafana

Für Grafana brauchst du keine eigene Schnittstelle: Grafana liest die Werte aus Prometheus.

1. In Grafana unter Connections → Data sources eine Datenquelle vom Typ Prometheus anlegen und die Adresse deines Prometheus-Servers eintragen.
2. Ein neues Dashboard anlegen und Panels mit den Abfragen unten hinzufügen.
3. Optional eine Variable für mehrere Nodes anlegen, zum Beispiel mit label_values(node64_info, node_name).

Eine fertige Dashboard-Vorlage gibt es nicht – mit diesen Abfragen ist ein eigenes Dashboard aber schnell gebaut:

Messwerte zu Online-Checks aus Nürnberg und Falkenstein siehst du zusätzlich im Portal von ipv64.net, wenn deine Node verknüpft ist.

Etwas unklar, fehlt etwas oder hast du eine Frage zu Node64? Frag im offiziellen Forum v64.tech.