> Section: [8. Observing it](https://jaque.sh/docs/ui/dashboard.md)
> Next: nagios-compat/overview
> Index: https://jaque.sh/llms.txt


The archive is the event log's cold tier. A sink normally sees perfdata;
the archive sink sees the whole log -- every decision the engine ever
made -- and writes it as zstd-compressed JSON lines, one event per line,
sealed into segments named by the sequence range they cover, to a local
directory or an S3-compatible bucket. It is a consumer of the log and
never a source of truth: replay goes through the event log, and the
archive is what you read with `zstd`, `jq`, ClickHouse or DuckDB when
jaque is not running, or years later. It is off until declared.

## 1. What it archives

The entire event log: every event's `Codec` envelope, one JSON line
each, in the order of the log's sequence numbers. It is declared as a
sink with `type: "archive"`, whose `input` is fixed to `events`.

```cue
sinks: {
	log: {
		type:          "archive"
		url:           "file:///var/lib/jaque/archive"
		segment_bytes: 67108864
	}
}
```

Two URL forms are accepted.

| Form | Destination |
|---|---|
| `file:///dir` | a local directory |
| `s3://[KEY:SECRET@]bucket/prefix?endpoint=host:port&spool=/dir` | an S3-compatible bucket, with `spool` as the local directory segments are built in before upload; `region` and `insecure=true` are optional query parameters |

Credentials for the S3 form come from the URL's userinfo when present,
otherwise from `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in the
environment.

## 2. Segments

`segment_bytes` (default 64 MiB) is the uncompressed size at which a
partial segment is sealed. Sealed files are named
`events-<first>-<last>.jsonl.zst` after the first and last sequence they
contain, so the set of files is an index of the log by range.

On startup, `Recover` truncates a segment that was mid-write to its last
complete line, seals it, and the archive follower resumes right after the
last sequence already archived. A crash mid-segment neither corrupts the
archive nor loses an event silently: the event the truncated line held is
still in the log and is archived again in the next segment.

Several `archive` sinks with different `url`s coexist without conflict:
the `sinks:` block allows as many as there are destinations.

## 3. Reading it without jaque

The format is the point: plain JSON lines, zstd-compressed, no reader of
jaque's own required.

```sh
zstd -dc events-*.jsonl.zst | jq .
```

```sql
-- ClickHouse
SELECT * FROM file('events-*.jsonl.zst', JSONEachRow)
```

```sql
-- DuckDB
SELECT * FROM read_json('events-*.jsonl.zst')
```

The line format is the event log's own envelope, documented in
[Event log schema](https://jaque.sh/docs/reference/event-log-schema.md).

## 4. Where it runs

The archive has `input: "events"`, so it runs under `-target all` or
`-target engine`, which read the whole log, and is dropped by
`-target sink`, which shards the log by object ownership; see
[Sinks and perfdata](https://jaque.sh/docs/observability/sinks-and-perfdata.md), section 6.
Its lag behind the log is `jaque_eventlog_consumer_lag{follower="sink/<name>"}`.

## 5. Off by default

Like every sink, the archive is opt-in. No archive exists until the
operator declares one under `sinks:`; nothing is written anywhere until it
is pointed somewhere.

## 6. Security considerations

The archive is the complete event log, including check output, in clear
text once decompressed. Treat the directory or bucket as you would the
log itself. An S3 URL with `KEY:SECRET@` in it makes the CUE config a
secret; the environment form keeps credentials out of the file. The
archive opens no listener and makes outbound connections only to the
configured endpoint.