Snapshots

A snapshot is a point-in-time view of what Prelude Collector currently holds in memory for a device. It returns the latest parsed entries together with the raw protocol updates that produced them — without triggering a new collection cycle and without requiring a downstream consumer to be attached.

Snapshots are the right tool when you want to answer questions like:

• Is my new field mapping actually picking up data from the device?
• Why does this entry have an empty value — bad mapping, bad transform, or no raw update at all?
• Is this device sending fresh data, or has the cache gone stale?
• What does the data look like right now, before I plug a Grafana dashboard or NATS consumer onto it?

When a snapshot is produced

The collector maintains an in-memory cache for every active subscription on every device in its active pool. Each time the protocol delivers a new update, the cache is replaced atomically. A snapshot read is a lock-free copy of whatever is currently in that cache.

There are two important consequences:

1. A snapshot reflects collection state, not device state. If the device is healthy but the collector is disconnected, the snapshot returns whatever was last cached.
2. Snapshots are only available for actively-collecting devices. If the device is not in the active collector pool — for example, it was removed from a subscription, or the collector has not yet established a session — the endpoint returns 404.

You can also force an immediate refresh on the single-model endpoint (see below). This adds a small amount of latency but guarantees the returned data is current.

Inspecting a snapshot

Snapshots live under the collector REST API on port 4030 and require a Bearer token. Two endpoints are available — see the API reference for full request and response details:

• All models for a device — returns the latest cached data for every model currently subscribed on the device, grouped by model name.
• Single model for a device — returns one model's snapshot, with an optional flag to force an immediate refresh before returning.

A typical single-model response carries two arrays:

{
  "device-id": 1,
  "device": "router-core-01.example.com",
  "model-name": "interfaces",
  "timestamp": "2026-04-28T10:29:58Z",
  "entries": [
    {
      "device": "router-core-01.example.com",
      "device-id": 1,
      "model-name": "interfaces",
      "path": "/interfaces/interface/state",
      "key": "GigabitEthernet0/0/1",
      "timestamp": "2026-04-28T10:29:58Z",
      "data-hash": "9f86d081884c7d65",
      "data": {
        "name": "GigabitEthernet0/0/1",
        "admin-status": "UP",
        "oper-status": "UP",
        "in-octets": 1234567890,
        "out-octets": 987654321
      }
    }
  ],
  "raw-updates": [
    {
      "device": "router-core-01.example.com",
      "device-id": 1,
      "model-name": "interfaces",
      "path": "/interfaces/interface[name=GigabitEthernet0/0/1]/state/oper-status",
      "timestamp": "2026-04-28T10:29:58Z",
      "data": "UP"
    }
  ]
}

The two arrays let you correlate a parsed field value back to the exact protocol update that produced it.

entries (parsed data)

Each entry represents one logical object — one interface, one BGP peer, one optical channel. Fields:

Per-field parse errors are not returned here — they are excluded from the snapshot payload by design and broadcast on a separate SSE channel so consumers that just want the data can ignore them. Use the Health endpoints (data-quality family) to surface parse errors for alerting.

raw-updates (raw protocol data)

Each entry is one protocol-level update before any parsing:

Curl examples

export COLLECTOR=https://collector.example.com:4030
export TOKEN="<your-api-token>"

# Every model for device 1
curl -s -H "Authorization: Bearer $TOKEN" \
  "$COLLECTOR/api/v1/snapshots/1"

# Just the interfaces model
curl -s -H "Authorization: Bearer $TOKEN" \
  "$COLLECTOR/api/v1/snapshots/1/interfaces"

# Force a fresh poll before returning
curl -s -H "Authorization: Bearer $TOKEN" \
  "$COLLECTOR/api/v1/snapshots/1/interfaces?refresh=true"

Bruno: 06 Snapshots / Get device snapshot, 06 Snapshots / Get model snapshot, 06 Snapshots / Refresh snapshot

For local installs use https://collector.example.com.

Common workflows

Verify a new field mapping. After adding a mapping, fetch the single-model snapshot and compare entries[*].data (the parsed output) against raw-updates[*].path (the raw input). Empty values in data with non-empty raw updates point at the mapping or transform.

Debug parse errors. Parse errors are not in the snapshot payload itself — they ride a dedicated SSE channel (so high-volume parse failures don't bloat every snapshot read). For a one-off look, use the Health endpoints: the data-quality family surfaces per-subscription parse-error counts, missing key fields, type coercion mismatches, and format failures with the field name and reason.

Check freshness ahead of the health engine. The model-level timestamp is the most recent update seen in the cache. Compare it against the current time and the subscription interval — drift is visible here before it crosses a health threshold.

Inspect data without a downstream consumer. During development, a snapshot is faster than spinning up a consumer on the output backend. Use ?refresh=true on the single-model endpoint to force an immediate poll.

Validate a model before enabling production. After publishing a new model definition, snapshot it on a real device to confirm every expected field is present and correctly typed before any dashboard or alert depends on it.

Retention

Snapshots are live — they reflect whatever is in the in-memory cache at the moment of the request. They are not persisted, not archived, and not searchable historically. For trend or after-the-fact investigation, use Metrics (time series) or your output backend (durable storage of the data itself).

See also

• Health — evaluated severity for every subscription.
• Metrics — Prometheus time series for collection rate, drops, and saturation.
• API reference — full snapshot endpoint reference.