Reference

Snapshot format

Elevarq Signals keeps collected snapshots in a local SQLite store and produces a portable ZIP only when you export. This page documents both: the store, the signals-snapshot.v1 export layout, the contents of each file in the ZIP, and the shape of metadata.json.

The store vs. the export

Signals does not leave a pile of ZIP files on disk as it runs. Every collection is appended to a single local SQLite database at database.path (default /data/signals.db). That database is the store. A ZIP file exists only once you run an export.

Snapshots older than retention_days (default 30) are pruned from the store. The store is append-on-collect, prune-on-retention; it is not a directory of loose snapshot files.

Running in Docker, the store lives inside the container at /data/signals.db (the /data volume). The export ZIP is a separate, on-demand artifact written to the path you choose.

The export

Export packages snapshots from the store into a portable ZIP that follows the signals-snapshot.v1 schema. With no content flags, an export contains the latest completed snapshot for each active target. Credentials never appear in exports — nor in the store, logs, or metrics.

For the commands that produce and consume a snapshot — export selection flags, Docker extraction, and handing the ZIP to Analyzer — see Export & use snapshots.

ZIP layout

A signals-snapshot.v1 export is a plain ZIP of JSON and NDJSON files — no proprietary container, no embedded credentials:

snapshot.zip
├── metadata.json        # schema + collector version, PG version, target
├── query_catalog.json   # which queries were executed
├── query_runs.ndjson    # per-run timing, row counts, and errors
└── query_results.ndjson # the collected rows, one JSON object per line

When signals.export_per_collector_files: true is set, the export additionally emits a per-collector/<id>.json file per collector inside the ZIP.

File contents

metadata.json

Identifies the schema version, the collector that produced the export, and the PostgreSQL target it was collected from. See metadata.json shape below.

query_catalog.json

Records which queries were executed to produce the snapshot.

query_runs.ndjson

One JSON object per line, describing each query run: per-run timing, row counts, and any errors.

query_results.ndjson

The collected rows, one JSON object per line. This is the data a downstream consumer reads directly or hands to Elevarq Analyzer.

per-collector/<id>.json

Present only when export_per_collector_files is enabled — one file per collector, keyed by collector ID.

metadata.json shape

metadata.json carries the schema version, collection context, and target identity:

{
  "schema_version": "signals-snapshot.v1",
  "collector_version": "<collector release version>",
  "collector_commit": "<source commit hash>",
  "collected_at": "<RFC 3339 timestamp>",
  "pg_version": "<PostgreSQL server version>",
  "target": {
    "name": "<target name>",
    "host": "<target host>",
    "port": 5432,
    "dbname": "<database name>"
  }
}

schema_version — always signals-snapshot.v1 for this format.
collector_version — the Signals collector release that produced the export.
collector_commit — the source commit hash of that collector build.
collected_at — when the snapshot was collected.
pg_version — the PostgreSQL server version of the target.
target — the collected target's name, host, port, and dbname. No credentials are included.