mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-02-18 00:17:39 +01:00
80cdfab536
- Use canonical types (vm, container, dockerContainer) instead of aliases (guest, docker) in examples - Document that guest/docker aliases are accepted by the API - Clarify persistent store type mapping in data flow doc
81 lines
2.6 KiB
Markdown
81 lines
2.6 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
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.
|