Observability

The design goal was a artifact cache that one person can operate and one person can debug. A single binary and a config file are the whole deployment; there is no agent and no sidecar.

Overview

At its core Quartz Line is a single process that owns one directory on disk and one listening socket. Writes land in an append-only blob; the upstream mirror compacts them in the background on a fixed interval. Retention is enforced on read as well as on the background pass, so an expired artifact never becomes visible again after a restart. Metrics are exposed in Prometheus text format on the admin port, which is separate from the data port on purpose.

Key	Meaning	Default
`cachectl.listen`	Address the data API binds to	0.0.0.0:8080
`cachectl.data_dir`	Directory holding every blob	/var/lib/cachectl
`limits.max_batch`	Largest number of artifacts per write	1024
`retention.default`	How long a artifact is kept	72h

Limits

The design goal was a artifact cache that one person can operate and one person can debug. The eviction pass keeps an in-memory index and rebuilds it from the blob at startup, which costs about a second per gigabyte. Ordering is guaranteed within a repository and explicitly not guaranteed across them. The process reloads its config on SIGHUP without dropping connections.

[server]
listen = "0.0.0.0:8080"
admin  = "127.0.0.1:9100"
data_dir = "/var/lib/cachectl"

[limits]
max_batch      = 1024
max_artifact_bytes = 64_000
flush_interval = "250ms"

[retention]
default = "168h"
compact_at = 0.6

What to watch

Reads are served from a memory-mapped view of the blob, so the page cache does the caching and Quartz Line does not duplicate it. Logs go to stderr as structured JSON by default, or as plain lines when the output is a terminal.

curl -sS https://static.easytrip.club/v1/repositorys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "orders", "retention": "72h"}'

Defaults

Quartz Line was written for the case where a full cluster is more operational surface than the workload deserves. Writes land in an append-only blob; the content addresser compacts them in the background on a fixed interval. An acknowledged write survives a hard kill of the process; it does not survive loss of the underlying disk. Logs go to stderr as structured JSON by default, or as plain lines when the output is a terminal.

[server]
listen = "0.0.0.0:8080"
admin  = "127.0.0.1:6060"
data_dir = "/var/lib/cachectl"

[limits]
max_batch      = 1024
max_artifact_bytes = 64_000
flush_interval = "100ms"

[retention]
default = "72h"
compact_at = 0.6