Getting started

Thanos provides a global query view, high availability, data backup with historical, cheap data access as its core features in a single binary.

Those features can be deployed independently of each other. This allows you to have a subset of Thanos features ready for immediate benefit or testing, while also making it flexible for gradual roll outs in more complex environments.

In this quick-start guide, we will explain:

How to ask questions, build and contribute to Thanos.
A few common ways of deploying Thanos.
Links for further reading.

Thanos will work in cloud native environments as well as more traditional ones. Some users run Thanos in Kubernetes while others on the bare metal.

Dependencies

Thanos aims for a simple deployment and maintenance model. The only dependencies are:

One or more Prometheus v2.2.1+ installations with persistent disk.
Optional object storage
- Thanos is able to use many different storage providers, with the ability to add more providers as necessary.

Get Thanos!

You can find the latest Thanos release here.

Main should be stable and usable. Every commit to main builds docker image named main-<data>-<sha> in quay.io/thanos/thanos and thanosio/thanos dockerhub (mirror)

We also perform minor releases every 6 weeks.

During that, we build tarballs for major platforms and release docker images.

See release process docs for details.

Building from source:

Thanos is built purely in Golang, thus allowing to run Thanos on various x64 operating systems.

Thanos can not be downloaded nor installed via the go get or go install methods. Starting in Go 1.17, installing executables with go get is deprecated. go install may be used instead. However, in order to avoid ambiguity, when go install is used with a version suffix, all arguments must refer to main packages in the same module at the same version. If that module has a go.mod file, it must not contain directives like replace or exclude that would cause it to be interpreted differently if it were the main module.

Thanos uses the directive replace. The reason is to provide a way to unblock ourselves promptly while also being flexible in the packages that we (re)use. Support for go install is not likely at this point.

If you want to build Thanos from source you would need a working installation of the Go 1.18+ toolchain (GOPATH, PATH=${GOPATH}/bin:${PATH}). Next one should make a clone of our repository:

git clone git@github.com:thanos-io/thanos.git

When you have access to the source code locally, we have prepared a Makefile. Invoke this by using make in your CLI. For example make help will list all options. For building Thanos one could use make build

The thanos binary should now be in your project folder and is the only thing required to deploy any of its components.

Contributing

Contributions are very welcome! See our CONTRIBUTING.md for more information.

Community

Thanos is an open source project and we value and welcome new contributors and members of the community. Here are ways to get in touch with the community:

Slack: #thanos
Issue Tracker: GitHub Issues

Maintainers

See MAINTAINERS.md.

Community Thanos Kubernetes Applications

Thanos is not tied to Kubernetes. However, Kubernetes, Thanos and Prometheus are part of the CNCF so the most popular applications are on top of Kubernetes.

Our friendly community maintains a few different ways of installing Thanos on Kubernetes. See those below:

prometheus-operator: Prometheus operator has support for deploying Prometheus with Thanos
kube-thanos: Jsonnet based Kubernetes templates.
Community Helm charts

If you want to add yourself to this list, let us know!

Deploying Thanos

Detailed, free, in-browser interactive tutorial as Killercoda Thanos Course
Quick Tutorial on Thanos website.

Operating

See up to date jsonnet mixins We also have example Grafana dashboards here and some alerts to get you started.

Talks

2024
2023
- Planetscale monitoring: Handling billions of active series with Prometheus and Thanos
- Taming the Tsunami: low latency ingestion of push-based metrics in Prometheus
2022
2021
2020
2019
2018
- Very first Prometheus Meetup Slides

Blog posts

2024:
- Scaling Prometheus with Thanos.
- Streamlining Long-Term Storage Query Performance for Metrics With Thanos.
2023:
- Thanos Ruler and Prometheus Rules — a match made in heaven.
2022:
2021:
- Adopting Thanos at LastPass
2020:
- Banzai Cloud user story
- Monitoring the Beat microservices: A tale of evolution
2019:
2018:

Integrations

See Integrations page.

Testing Thanos on Single Host

We don't recommend running Thanos on a single node on production. Thanos is designed and built to run as a distributed system. Vanilla Prometheus might be totally enough for small setups.

However, in case you want to play and run Thanos components on a single node, we recommend following the port layout:

Component	Interface	Port
Sidecar	gRPC	10901
Sidecar	HTTP	10902
Query	gRPC	10903
Query	HTTP	10904
Store	gRPC	10905
Store	HTTP	10906
Receive	gRPC (store API)	10907
Receive	HTTP (remote write API)	10908
Receive	HTTP	10909
Rule	gRPC	10910
Rule	HTTP	10911
Compact	HTTP	10912
Query Frontend	HTTP	10913

You can see example one-node setup here.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!