Observability — Logs & Metrics from the CLI

Since CLI 0.46.0, platform logs and metrics can be queried directly from the terminal with polycrate logs and polycrate metrics. The CLI uses the Polycrate API as a proxy to VictoriaLogs and VictoriaMetrics.

Observability — Logs & Metrics from the CLI

Since Polycrate CLI 0.46.0, platform logs and metrics can be queried directly from the terminal — without Grafana access. The CLI talks to the Polycrate API, which transparently forwards requests to VictoriaLogs (logs) and VictoriaMetrics (metrics).

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

→ [API integration](/docs/polycrate/api/)

The workspace is loaded via `-w` as usual; organization and workspace name come from `workspace.poly`.

polycrate logs

Queries logs for the organization of the loaded workspace. Optionally the query can be restricted to a block within the workspace.

Basic usage

cd ~/.polycrate/workspaces/acme/production

# All logs of the workspace (default query: *)
polycrate logs

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

# Restrict to a block
polycrate logs --block victoria-logs --limit 50

polycrate logs list is an alias with identical behavior (backwards compatibility).

Flags

Flag Short Default Description
--query * LogsQL query (transparent passthrough to VictoriaLogs)
--block — Scope to a block instance in the workspace
--start — Time range start (RFC3339 or VictoriaLogs duration, e.g. 5m)
--end — Time range end (RFC3339 or duration)
--limit 100 Maximum number of results
--format table json for machine-readable output
--follow -f false Client-side polling for new entries (like tail -f)
--follow-interval 2s Polling interval with --follow
-w, --workspace $PWD Path to the workspace

Output

Default (table): columns TIME, SEVERITY, MESSAGE — severity is color-highlighted.

JSON: raw log entries as a JSON array (recommended for scripting and coding agents):

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

Follow mode

--follow polls the same query at an interval and prints newly appearing entries chronologically. This is client-side polling, not a server-push tail — sufficient for interactive debugging and agent workflows.

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

API endpoint

The CLI uses GET /api/v1/logs/query with the parameters organization, workspace, block, query, start, end, limit. Org/workspace/block are passed as names (not as UUIDs).

polycrate metrics

Runs PromQL or MetricsQL queries against VictoriaMetrics — scoped to organization, workspace and optionally block.

Basic usage

# Instant query
polycrate metrics 'up'

# With block scope
polycrate metrics 'rate(http_requests_total[5m])' --block nginx

# Range query (automatic when --start, --end or --step is set)
polycrate metrics 'up' --start -1h --end now --step 1m

# JSON (raw VictoriaMetrics response)
polycrate metrics 'up' --format json

Flags

Flag Description
<query> PromQL/MetricsQL (positional argument, required)
--block Scope to a block instance
--time Evaluation time for an instant query (RFC3339 or Unix)
--start Range start — triggers a range query
--end Range end — triggers a range query
--step Resolution of the range query (default: 1m when range is active)
--format json for the raw API response; default: table
-w, --workspace Workspace path

Instant vs. range query

As soon as one of the flags --start, --end or --step is set, a range query (query_range) is executed automatically instead of an instant query — analogous to the server-side behavior of the Polycrate API.

Output

Default (table): labels and value(s) per series. For range results (matrix) the table shows a compact summary (last value, number of data points).

JSON: unchanged VictoriaMetrics/Prometheus API structure (status, data.resultType, data.result).

API endpoints

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

Typical workflows

Operator without Grafana

cd ~/.polycrate/workspaces/ayedo/laser24

# Errors of the last hour
polycrate logs --query 'severity:error' --start 1h

# Availability of a block
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]'

Migration from polycrate logs (old)

Old (≤ 0.45.0) New (≥ 0.46.0)
Local .logs/ YAML files API query against VictoriaLogs
polycrate logs inspect <txid> Removed — filter logs via --query
events.handler: workspace in workspace.poly Removed — no local event persistence anymore

See also