Pulse/docs/METRICS_HISTORY.md

Metrics History (Persistent)

Pulse persists metrics history to disk so trend views and sparklines survive restarts.

Storage Location

Metrics history is stored in a SQLite database named metrics.db under the Pulse data directory:

• systemd/LXC installs: typically /etc/pulse/metrics.db
• Docker/Kubernetes installs: typically /data/metrics.db

Retention Model (Tiered)

Pulse keeps multiple resolutions of the same data, which allows longer history without storing raw samples forever:

• Raw (high-resolution, short window)
• Minute aggregates
• Hourly aggregates
• Daily aggregates

Default retention values (subject to change) are:

• Raw: 2 hours
• Minute: 24 hours
• Hourly: 7 days
• Daily: 90 days

Advanced: Retention Tuning

Tiered retention is stored in system.json in the Pulse data directory:

• systemd/LXC installs: typically /etc/pulse/system.json
• Docker/Kubernetes installs: typically /data/system.json

Keys:

{
  "metricsRetentionRawHours": 2,
  "metricsRetentionMinuteHours": 24,
  "metricsRetentionHourlyDays": 7,
  "metricsRetentionDailyDays": 90
}

After changing these values, restart Pulse.

API Access

Pulse exposes the persistent metrics store via:

• GET /api/metrics-store/stats
• GET /api/metrics-store/history

These endpoints require authentication with the monitoring:read scope.

History Query Parameters

GET /api/metrics-store/history supports:

• resourceType (required): node, vm, container, storage, dockerHost, dockerContainer
• resourceId (required): resource identifier (for guests use instance:node:vmid)
• metric (optional): cpu, memory, disk, etc. Omit to return all metrics for the resource.
• range (optional): 1h, 6h, 12h, 24h, 1d, 7d, 30d, 90d (default 24h; duration strings also accepted)
• maxPoints (optional): Downsample to a target number of points

Example:

curl -H "X-API-Token: $TOKEN" \
  "http://localhost:7655/api/metrics-store/history?resourceType=vm&resourceId=pve1:node1:100&range=7d&metric=cpu"

License: Requests beyond 7d require the Pulse Pro long_term_metrics feature. Unlicensed requests return 402 Payment Required. Aliases: guest (VM/LXC) and docker (Docker container) are accepted, but persistent store data uses the canonical types above.

Troubleshooting

• No sparklines / empty history: confirm the instance can write to the data directory and that metrics.db exists.
• Large disk usage: reduce polling frequency first. If you need tighter retention, adjust the tiered retention settings in system.json (advanced) and restart Pulse.