Thanos: Long-Term Metric Storage and Global Query View for Prometheus

What Thanos Solves and How It Fits Alongside Prometheus

Prometheus is a time-series database that stores metrics locally on disk. Two constraints follow from that design: the retention period is limited by local disk size, and querying data from multiple Prometheus instances requires querying each one separately.

Thanos solves both. It reads the Prometheus 2.0 storage format directly and ships blocks of metric data to any object storage backend, removing the disk retention ceiling. A global query component called Thanos Query provides a single PromQL endpoint that proxies requests across all connected Prometheus instances, merging results on the fly. For high-availability Prometheus pairs, Thanos Query deduplicates identical metrics collected by both instances.

The project's stated aims are three: a global query view across Prometheus installations, unlimited metric retention, and high availability of components including Prometheus itself. None of these require modifying the Prometheus binary; Thanos attaches to an existing Prometheus setup.

Core Components and Their Roles

Thanos is not a monolith. The README describes it as a set of components that can be composed into a metric system. Each subcommand does one thing, following a Unix-style philosophy. The primary components visible in the repository's cmd directory include:

The Sidecar attaches to a Prometheus instance, reads its local data blocks, and uploads them to object storage. It also exposes the Store API so Thanos Query can reach that Prometheus instance's data.

Thanos Query is the global query frontend. It receives PromQL queries and fans them out to any number of Store API endpoints, then merges and deduplicates the results. Thanos Store reads historical blocks from object storage and exposes them through the same Store API, so the query layer treats local and remote data uniformly.

The Receive component implements the Prometheus remote write API, which allows Prometheus instances or other remote write sources to push data directly to Thanos instead of requiring a sidecar. This supports setups where a sidecar cannot be co-located with Prometheus.

Installation and the Sidecar Deployment Pattern

The main branch of the Thanos repository is kept stable and usable. Every commit to main produces a Docker image named `main-<date>-<sha>` at quay.io/thanos/thanos. Minor releases happen every six weeks. The Dockerfile in the repository uses a busybox base image and runs the thanos binary as a non-root user with uid 1001.

For Kubernetes deployments, the README describes the primary pattern as adding a Sidecar container to each Prometheus Pod. The Sidecar requires access to the Prometheus data directory and to object storage credentials. A second deployment pattern using Receive scales out by accepting remote write instead of co-locating with Prometheus pods.

The documentation site at thanos.io hosts the Getting Started guide, the component reference, and the architecture diagrams. The repository also includes a tutorials directory and an integrations documentation file at docs/integrations.md.

Binary tarballs for major platforms are published at each minor release alongside Docker images. The go.mod file specifies Go 1.26.0 as the module language version.

Object Storage Integration and Downsampling

Any object storage that exposes an S3-compatible API, Google Cloud Storage, Azure Blob Storage, or OpenStack Swift can serve as Thanos's long-term storage backend. The storage abstraction is pluggable; the docs/integrations.md file covers supported providers.

Historical data in object storage can be downsampled by the Thanos Compact component. Downsampling reduces query latency for long time ranges by precomputing lower-resolution data. The README notes that Thanos stores data in native Prometheus format, meaning the blocks are readable by Prometheus tooling as well as Thanos.

The simple gRPC Store API is the internal protocol that all data-serving components implement. This uniform interface means the query layer does not need to know whether a backend is a live Prometheus sidecar, a historical object storage block, or a Receive ingester.

Limitations: Operational Complexity and Component Count

Thanos's component model is its main trade-off. Running the full stack (Prometheus, Sidecar, Query, Store, Compact, and possibly Receive) means operating and monitoring several distinct processes with their own configurations, health checks, and failure modes. For a single-site Prometheus deployment, this overhead is rarely justified.

Query deduplication depends on consistent labels across HA pairs. If two Prometheus instances in a HA pair scrape with different external labels, deduplication will not work correctly. The deduplication logic expects specific replica labels to be configured.

The Thanos Compact component must run in single-instance mode: two Compact processes running against the same object storage bucket will produce corrupted data. The documentation covers this constraint, but it is a deployment error that cannot be detected automatically until after damage is done.

How Thanos Compares to Cortex

Cortex is another CNCF project for horizontally scalable, long-term Prometheus storage. The two projects share some architectural ideas: both use object storage, both implement the Prometheus remote write protocol, and both provide a global query interface.

The practical difference is in the scaling model. Cortex is designed as a shared, multi-tenant service where all the ingestion, querying, and compaction components are broken into microservices that scale independently. Thanos is designed to attach to existing Prometheus deployments and compose components gradually; there is no requirement to move all ingestion to a single centralized system.

For a team starting from one or a few Prometheus instances and wanting to add long-term storage without redesigning the ingestion pipeline, Thanos fits more naturally. For a team building a shared observability platform for many tenants from the start, Cortex's purpose-built multi-tenancy is worth evaluating.

Release Cadence and Community

Thanos performs minor releases every six weeks, as documented in the release process docs at docs/release-process.md. The last release listed in the repository is v0.42.4, published on 2026-07-30. The last push was on 2026-09-23.

The project is a CNCF Incubating project. Community communication happens through the CNCF Slack at the #thanos channel (linked at slack.cncf.io) and through GitHub Issues. The adopters list is at website/data/adopters.yml. The codebase is Apache-2.0 licensed, and the mixin directory contains Prometheus alerting rules and dashboards for monitoring Thanos itself.

Editorial conclusion

Thanos is the right extension for teams running multiple Prometheus instances that need unified querying across all of them, long-term storage beyond local disk, or high-availability metric deduplication. It does not replace Prometheus; it requires Prometheus to be running first and adds components on top. Teams running a single Prometheus instance with retention requirements that fit on local disk will find less to justify the operational overhead of Thanos's additional components.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. thanos-io/thanos on GitHub