Configure the Thanos Compactor to downsample metrics and manage retention in object storage
domain: thanos.io · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Run `thanos compact --data-dir <dir> --objstore.config-file=bucket.yml` as a single singleton instance against a given bucket/block-stream — only one Compactor may safely operate on the same stream (grouped by external labels) at a time.
Downsampling runs automatically in two passes: 5-minute-resolution blocks are produced from raw blocks older than 40 hours, and 1-hour-resolution blocks are produced from 5m blocks older than 10 days; disable it entirely with `--downsampling.disable` if not needed.
Set `--retention.resolution-raw`, `--retention.resolution-5m`, and `--retention.resolution-1h` to durations (e.g. `--retention.resolution-raw=30d`) to control how long each resolution tier is kept in the bucket; leaving them at the default `0d` retains that resolution forever.
Keep retention at each resolution greater than or equal to the minimum age required for the next downsampling pass (e.g. raw/5m retention should exceed 10 days) so data isn't deleted before it can be downsampled into the next tier.
Run the Compactor continuously with `--wait --wait-interval=5m`, or invoke it as a periodic batch/cron job, since by default it exits once it finishes a compaction pass.
Tune `--compact.concurrency`, `--consistency-delay` (default 30m, delay before newly-uploaded blocks are considered for compaction), and `--delete-delay` (default 48h, grace period before deletion-marked blocks are physically removed) to match bucket size and object-storage consistency guarantees.
Known gotchas
Downsampling does not save storage space — it adds two extra downsampled block resolutions per raw block, which can increase total object storage usage by roughly 3x if all resolutions are retained.
Only one Compactor may run against a single stream of blocks in a bucket; running multiple instances against the same stream risks unresolvable block overlaps. Scale horizontally via label-based sharding (relabel-config), not by simply adding replicas.
The Compactor halts rather than crashing when it detects an unsafe state such as overlapping blocks (metric `thanos_compact_halted` set to 1) — a halted Compactor silently stops all progress, including retention and downsampling, until the issue is manually resolved, so this metric should be alerted on.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?