Zum Inhalt

Metriken der Polycrate API

Die Polycrate API stellt Metriken in drei Schichten bereit, die über ein gemeinsames Contract-Pattern (MetricsMixin) vereinheitlicht sind und alle gegen VictoriaMetrics abgefragt werden.

Schicht Endpunkt Format Konsument
Prometheus-Export GET /api/v1/metrics text/plain VMAgent → VictoriaMetrics
System-Metriken GET /api/v1/system/metrics/ JSON Dashboard-Widget (System-Übersicht)
Objekt-Metriken GET /api/v1/{model}/{id}/metrics/ JSON Metric-Tabs auf jeder Detail-Seite

System- und Objekt-Metriken nutzen denselben {data, meta, chart_spec}-Response-Shape und werden vom einheitlichen metricChart Alpine.js-Komponent in der UI gerendert.

Prometheus-Export

Übersicht

Unter GET /api/v1/metrics liefert die Polycrate API Prometheus-kompatible Metriken — ohne Authentifizierung, damit VMAgent/Prometheus ohne Token scrapen kann.

  • Endpoint: /api/v1/metrics
  • Caching: Alle Metriken werden alle 60 Sekunden per Celery-Task vorberechnet und mit TTL 120 s in Redis gecacht. Scrapes unter Last antworten in < 100 ms aus dem Cache; ein Cache-Miss generiert live nach.
  • Basis-Labels: Jede Serie trägt polycrate_io_metrics_source="api" und polycrate_io_system_name="<instance>", so dass sich API-Metriken in VictoriaMetrics eindeutig von Agent-, Operator- oder Kubernetes-Metriken trennen lassen.

Label-Prefix

Metriknamen beginnen mit polycrate_io_api_. Das Label-Schema polycrate_* (ohne io) gilt für Metriken aus externen Quellen (Agent, Operator, kube-state-metrics, blackbox-exporter). Siehe Labels & Konventionen.

SLO/SLA

Metrik Beschreibung
polycrate_io_api_breaches_active_count Aktive SLO/SLA-Breaches nach Typ
polycrate_io_api_overall_availability_percent Gewichtete Verfügbarkeit (SLO/SLA)
polycrate_io_api_error_budget_consumed_avg_percent Ø verbrauchtes Error-Budget

Endpoint-Status

Metrik Beschreibung
polycrate_io_api_endpoints_by_state Endpoints nach State (OK, WARNING, CRITICAL)

Betrieb (Downtimes, Wartung, Actions)

Metrik Beschreibung
polycrate_io_api_action_runs_count Action Runs nach Status
polycrate_io_api_downtimes_active_count Aggregierte Anzahl aktiver Downtimes pro Organisation
polycrate_io_api_downtime_is_active Binärer Wert 1 pro aktiver Downtime — erzeugt Zeitreihen, aus denen die Downtime-Timeline gebaut wird. Absenz bedeutet „vorbei".
polycrate_io_api_downtime_affected_objects Anzahl aktuell betroffener Objekte pro Downtime (Time-Series via VMAgent)
polycrate_io_api_maintenances_active_count Aggregierte Anzahl laufender Wartungen pro Org/Workspace
polycrate_io_api_maintenance_is_active Binärer Wert 1 pro laufender Wartung

→ Downtime & Timeline · Wartungen · Wartungsfenster

Ressourcen (Zählwerte)

Metrik Beschreibung
polycrate_io_api_resource_count Ressourcen je Typ (K8sCluster, K8sApp, LoadbalancerInstance, S3Bucket, DNSZone, Domain) pro Organisation/Workspace
polycrate_io_api_workspaces_total Gesamtzahl Workspaces
polycrate_io_api_organizations_total Gesamtzahl Organisationen
polycrate_io_api_workspaces_count Workspaces pro Organisation

Ressourcen-Details (Org-Level, persistiert)

Werte aus Modell-Feldern, die alle ~5 Minuten von Reconciliation-Tasks aktualisiert werden — billig abfragbar, ohne dass der Prometheus-Export selbst S3/LB-Backends aufrufen muss.

Metrik Beschreibung
polycrate_io_api_s3_bucket_count Anzahl S3-Buckets pro Organisation
polycrate_io_api_s3_object_count Summe der S3-Objekte pro Organisation
polycrate_io_api_s3_storage_bytes Belegter S3-Speicher pro Organisation (Bytes)
polycrate_io_api_loadbalancer_instance_count Anzahl LoadbalancerInstances pro Organisation
polycrate_io_api_loadbalancer_traffic_bytes_per_second Summe der 1h-Mittelwerte der Bandbreite pro Organisation
polycrate_io_api_registry_storage_bytes Belegter Artifact-Registry-Speicher pro Organisation

S3-Cluster-Backend

Pro S3Cluster werden Backend-Kennzahlen aus der Reconciliation gegen Rook-Ceph oder MinIO gespiegelt (Details siehe S3 Buckets & Object Storage).

Metrik Backend Beschreibung
polycrate_io_api_s3cluster_ceph_osd_total_bytes rook-ceph OSD-Gesamtkapazität
polycrate_io_api_s3cluster_radosgw_logical_used_bytes rook-ceph Logisch belegter Speicher (radosgw)
polycrate_io_api_s3cluster_minio_capacity_usable_bytes minio Nutzbare Kapazität
polycrate_io_api_s3cluster_minio_usage_bytes minio Belegter Speicher
polycrate_io_api_s3cluster_managed_buckets_usage_bytes beide Summe über Polycrate-verwaltete Buckets
polycrate_io_api_s3cluster_managed_buckets_object_count beide Summe der Objekte in Polycrate-verwalteten Buckets

Projects & Notes

Metrik Beschreibung
polycrate_io_api_todos_count Todo-Notes nach Status (open, resolved) pro Org/Workspace

→ Projekte · Notes

Endpoint-Monitoring (Agents & Coverage)

Metrik Beschreibung
polycrate_io_api_agent_capacity Max. Endpoint-Kapazität pro Agent
polycrate_io_api_agent_assigned_endpoints Zugeordnete Endpoints pro Agent
polycrate_io_api_agent_utilization_percent Agent-Auslastung
polycrate_io_api_agent_checks_per_minute Checks pro Minute pro Agent
polycrate_io_api_endpoint_coverage_total Endpoints nach Coverage (uncovered, single, multi)
polycrate_io_api_endpoint_coverage_rate_percent Anteil Endpoints mit ≥ 1 Agent
polycrate_io_api_endpoint_multi_coverage_rate_percent Anteil Endpoints mit ≥ 2 Agenten
polycrate_io_api_endpoint_check_latency_avg_ms Ø Check-Latenz
polycrate_io_api_endpoint_checks_total Check-Zähler nach Status
polycrate_io_api_endpoint_check_success_rate_percent Success-Rate der Checks
polycrate_io_api_endpoint_monitoring_summary Zusammenfassung (für Alerting & Dashboards)

→ Endpoint-Monitoring

PoP-zu-PoP-Latenz

Metrik Beschreibung
polycrate_io_api_pop_latency_avg_ms Ø Latenz zwischen PoP-Paaren
polycrate_io_api_pop_latency_min_ms Minimum
polycrate_io_api_pop_latency_max_ms Maximum
polycrate_io_api_pop_check_count Anzahl Checks zwischen PoP-Paaren
polycrate_io_api_pop_assignment_count Anzahl aktiver Zuweisungen pro PoP-Paar

Activity-Metriken (neu ab 0.15.0)

Zeitreihen über Plattform-Events — Grundlage für die System-Charts auf dem Haupt-Dashboard. Alle Werte als 5-Minuten-Fenster; für Trends eignet sich increase(...[5m]).

Metrik Beschreibung
polycrate_io_api_recent_activities_count Alle Activity-Events (Audit-Trail, Lifecycle, Deployments…)
polycrate_io_api_recent_state_changes_count Nur kind="state_changed"
polycrate_io_api_recent_deployments_count ReplicaSet/StatefulSet-Deployments (aus K8s-Discovery)
polycrate_io_api_recent_block_action_runs_count Block-Action-Runs (Polycrate CLI → API)
polycrate_io_api_recent_ssh_sessions_count Neue SSH-Sessions über Bastions

→ Audit & Compliance

System-Metriken (Dashboard-Übersicht)

Unter GET /api/v1/system/metrics/ liefert die API plattformweite Zeitreihen im JSON-Format. Genutzt wird dieser Endpoint von den Widgets im Haupt-Dashboard (Tab „System-Übersicht"), die z. B. „Activities in den letzten 7 Tagen" darstellen.

Jede System-Metrik ist eine PromQL-Range-Query gegen die entsprechende Gauge aus dem Prometheus-Export:

System-Metrik Quell-Gauge Beschreibung
activities polycrate_io_api_recent_activities_count Alle Activity-Events
state_changes polycrate_io_api_recent_state_changes_count State-Änderungen
deployments polycrate_io_api_recent_deployments_count Deployments
block_action_runs polycrate_io_api_recent_block_action_runs_count Block-Action-Runs
ssh_sessions polycrate_io_api_recent_ssh_sessions_count SSH-Sessions

Der Endpoint akzeptiert dieselben Parameter wie Objekt-Metriken:

  • metric=<name> — ohne Parameter: Liste verfügbarer Metriken (Discovery)
  • time_from=<rfc3339>, time_to=<rfc3339> — Zeitfenster

Objekt-Metriken (Metric-Functions)

Auf der Detailseite jedes ManagedObjects stellt Polycrate Metric-Tabs bereit, die ohne Grafana-Setup direkt in der UI Time-Series-Charts rendern. Die Daten kommen aus VictoriaMetrics; abgefragt werden sie über den generischen Endpoint:

GET /api/v1/{model}/{id}/metrics/?metric=<name>&time_from=...&time_to=...

Was ist eine Metric-Function?

Eine Metric-Function ist eine am Objekt-Typ deklarierte Abfrage, die:

  1. das Objekt über seine Standard-Labels (polycrate_cluster, polycrate_customer, polycrate_workspace, ggf. polycrate_namespace) in VictoriaMetrics identifiziert,
  2. PromQL gegen Metriken aus Agents/kube-state-metrics/kubelet/blackbox-exporter fährt,
  3. das Ergebnis als Chart (line, area, bar) mit Einheit (bytes, bytes/s, %, cores, count) rendert.

Verfügbare Functions pro Objekttyp

Objekttyp Function(s) Beschreibung
Host cpu_usage, memory_usage CPU-Last & Memory-Belegung aus node-exporter
K8sCluster cpu_usage, memory_usage Aggregierte Cluster-Ressourcen (kube-state-metrics)
K8sApp pod_count, cpu_usage, memory_usage Metriken pro App-Workload
K8sVolume volume_usage Belegter vs. Gesamt-Speicher des PVC (kubelet)
S3Cluster backend_total_capacity, backend_logical_used Backend-Kapazität & logische Belegung (Ceph/MinIO)
S3Bucket bucket_usage, object_count Storage-Füllstand & Objektanzahl pro Bucket
LoadbalancerInstance bandwidth Ein-/Ausgehender Traffic pro LB-Instanz
Endpoint status_blocks, latency, uptime Blackbox-Check-Werte (Heatmap, Latenz-Kurve, Uptime-Prozent)
Agent checks_per_minute, utilization Arbeitslast eines Monitoring-Agents

Erweiterbar

Neue Functions werden zentral am Objekt-Modell deklariert (metric_functions-Dict mit display_name, description, method, chart_spec). Dadurch nutzt jedes Objekt dieselbe Tab-UI, denselben Zeitraum-Picker und dieselbe Auto-Step-Logik.

Zeitraum-Steuerung

Jedes Widget hat:

  • Zeitraum-Dropdown (1h, 6h, 24h, 7d, 30d, Custom)
  • „Reset to Initial Range" (bringt den Graph auf den Default-Zeitraum zurück)
  • Custom Range aus Downtime-Events — auf der Downtime-Timeline führt „Show in Metric" direkt mit passendem Zeitfenster in das Dashboard-Widget
  • Auto-Step: automatische Sample-Auflösung abhängig vom Zeitraum (1 h → 15 s, 7 d → 5 min, 30 d → 30 min)

Nutzung & Integration

Scraping-Konfiguration

# VictoriaMetrics / Prometheus scrape_config
scrape_configs:
  - job_name: 'polycrate-api'
    static_configs:
      - targets: ['api.polycrate.io']
    metrics_path: '/api/v1/metrics'

Da die API selbst alle Werte cached, ist ein Scrape-Intervall von 30 – 60 s empfohlen.

Typische Use-Cases

  • Kapazitätsplanung — Ressourcen-Zahlen, S3-Storage und Workspace-Wachstum überwachen
  • SLO-Dashboards — Availability und Error-Budget in Grafana visualisieren, gemeinsam mit Agent-Metriken (gleiches polycrate_*-Label-Schema)
  • Agent-Überwachung — Coverage, Auslastung und Checks/min der Monitoring-Agents prüfen
  • Incident-Response — von der Downtime-Timeline direkt ins passende Metric-Tab springen
  • Kunden-Reporting — Screenshots aus der UI zeigen Ressourcen-Trends ohne Grafana-Zugriff

Zusammenspiel mit Grafana

Metric-Functions und System-Widgets decken den operativen Quick-Look ab. Für tiefergehende Dashboards (Multi-Objekt-Overlays, komplexe Aggregationen, Alerting mit VMAlert) bleibt Grafana das Werkzeug der Wahl — die gemeinsamen polycrate_*-Labels sorgen dafür, dass dieselben Queries in UI und Grafana funktionieren.

Siehe auch