Zum Inhalt

Observability — Logs & Metriken aus der CLI

Ab Polycrate CLI 0.46.0 können Plattform-Logs und -Metriken direkt aus dem Terminal abgefragt werden — ohne Grafana-Zugriff. Die CLI spricht die Polycrate API an, die Anfragen transparent an VictoriaLogs (Logs) bzw. VictoriaMetrics (Metriken) durchreicht.

Voraussetzung: Polycrate API

Beide Befehle benötigen eine konfigurierte API-Verbindung in ~/.polycrate/polycrate.yml:

api:
  enabled: true
  url: https://app.ayedo.cloud
  api_key: <your-api-key>

→ API-Integration

Der Workspace wird wie gewohnt über -w geladen; Organisation und Workspace-Name stammen aus der workspace.poly.

polycrate logs

Fragt Logs für die Organisation des geladenen Workspaces ab. Optional kann auf einen Block innerhalb des Workspaces eingeschränkt werden.

Grundlegende Verwendung

cd ~/.polycrate/workspaces/acme/production

# Alle Logs des Workspaces (Default-Query: *)
polycrate logs

# LogsQL-Filter
polycrate logs --query '_msg:error'

# Auf einen Block einschränken
polycrate logs --block victoria-logs --limit 50

polycrate logs list ist ein Alias mit identischem Verhalten (Rückwärtskompatibilität).

Flags

Flag Kurz Standard Beschreibung
--query * LogsQL-Query (transparenter Passthrough an VictoriaLogs)
--block — Scope auf eine Block-Instanz im Workspace
--start — Zeitraum-Start (RFC3339 oder VictoriaLogs-Duration, z. B. 5m)
--end — Zeitraum-Ende (RFC3339 oder Duration)
--limit 100 Maximale Anzahl Ergebnisse
--format Tabelle json für maschinenlesbare Ausgabe
--follow -f false Client-seitiges Polling neuer Einträge (wie tail -f)
--follow-interval 2s Polling-Intervall bei --follow
-w, --workspace $PWD Pfad zum Workspace

Output

Standard (Tabelle): Spalten TIME, SEVERITY, MESSAGE — Severity farblich hervorgehoben.

JSON: Rohe Log-Einträge als JSON-Array (empfohlen für Scripting und Coding-Agents):

polycrate logs --query 'severity:error' --format json

Follow-Modus

--follow pollt die gleiche Query in einem Intervall und druckt neu erscheinende Einträge chronologisch. Das ist client-seitiges Polling, kein server-push Tail — ausreichend für interaktives Debugging und Agent-Workflows.

polycrate logs --follow --block polycrate-api --query '*'

API-Endpunkt

Die CLI nutzt GET /api/v1/logs/query mit Parametern organization, workspace, block, query, start, end, limit. Org/Workspace/Block werden als Namen übergeben (nicht als UUID).

polycrate metrics

Führt PromQL- bzw. MetricsQL-Abfragen gegen VictoriaMetrics aus — gescoped auf Organisation, Workspace und optional Block.

Grundlegende Verwendung

# Instant Query
polycrate metrics 'up'

# Mit Block-Scope
polycrate metrics 'rate(http_requests_total[5m])' --block nginx

# Range Query (automatisch wenn --start, --end oder --step gesetzt)
polycrate metrics 'up' --start -1h --end now --step 1m

# JSON (rohe VictoriaMetrics-Response)
polycrate metrics 'up' --format json

Flags

Flag Beschreibung
<query> PromQL/MetricsQL (positionales Argument, Pflicht)
--block Scope auf Block-Instanz
--time Evaluationszeitpunkt für Instant Query (RFC3339 oder Unix)
--start Range-Start — löst Range Query aus
--end Range-Ende — löst Range Query aus
--step Auflösung der Range Query (Default: 1m wenn Range aktiv)
--format json für rohe API-Response; Default: Tabelle
-w, --workspace Workspace-Pfad

Instant vs. Range Query

Sobald einer der Flags --start, --end oder --step gesetzt ist, wird automatisch eine Range Query (query_range) statt einer Instant Query ausgeführt — analog zum serverseitigen Verhalten der Polycrate API.

Output

Standard (Tabelle): Labels und Wert(e) pro Serie. Bei Range-Ergebnissen (matrix) zeigt die Tabelle eine kompakte Zusammenfassung (letzter Wert, Anzahl Datenpunkte).

JSON: Unveränderte VictoriaMetrics/Prometheus-API-Struktur (status, data.resultType, data.result).

API-Endpunkte

  • Instant: GET /api/v1/metrics/query
  • Range: GET /api/v1/metrics/query_range

Typische Workflows

Operator ohne Grafana

cd ~/.polycrate/workspaces/ayedo/laser24

# Fehler der letzten Stunde
polycrate logs --query 'severity:error' --start 1h

# Verfügbarkeit eines Blocks
polycrate metrics 'up{block="polycrate-api"}'

CI / Scripting

polycrate logs --query '_msg:OOM' --format json --limit 20 \
  -w /home/user/workspaces/acme/prod | jq '.[]._msg'

polycrate metrics 'sum(rate(http_requests_total[5m]))' --format json \
  -w /home/user/workspaces/acme/prod | jq '.data.result[0].value[1]'

Absoluter Workspace-Pfad

In CI und bei Container-Actions immer den absoluten Pfad für -w verwenden — relative Pfade wie -w . können bei Docker-Mounts fehlschlagen.

Migration von polycrate logs (alt)

Alt (≤ 0.45.0) Neu (≥ 0.46.0)
Lokale .logs/-YAML-Dateien API-Abfrage gegen VictoriaLogs
polycrate logs inspect <txid> Entfernt — Logs über --query filtern
events.handler: workspace in workspace.poly Entfernt — keine lokale Event-Persistenz mehr

Siehe auch