Grafana Tempo: a trace backend that needs only object storage

What Tempo stores that a metrics system cannot

Prometheus answers how many requests failed and how slow the p99 got. It cannot tell you which of the twelve services on the path of one slow request was the slow one. That is the gap Tempo fills: it stores spans, the individual timed operations inside a request, and lets you query them by attribute rather than by pre-aggregated series.

The intended reader is an operator who already has Grafana in front of Prometheus and Loki and wants traces in the same pane. The README describes Tempo as "deeply integrated with Grafana, Prometheus, and Loki", and the storage claim is the distinguishing one: Tempo runs on object storage alone. There is no Elasticsearch cluster, no Cassandra ring, no separate index database to size and back up. If your traces are currently sitting in a Jaeger deployment backed by a search engine, the operational surface you would remove is most of the reason to look at Tempo.

The second half of the pitch is TraceQL, which the README describes as "a traces-first query language inspired by LogQL and PromQL". If your team already writes LogQL against Loki, the shape of a trace query will not be new.

Ingest, buffer, write: the path a span takes

The README states the pipeline plainly: Tempo "ingests batches in any of the mentioned formats, buffers them, and then writes them to Azure, GCS, S3, or local disk". The compatible formats listed are Jaeger, Zipkin, Kafka and OpenTelemetry, so an existing collector fleet does not have to be rewritten to point at Tempo.

The standards commitment is structural rather than cosmetic. According to the README, Tempo's "receiver layer, wire format and storage format are all based directly on standards and code established by OpenTelemetry", and the repository carries an opentelemetry-proto submodule at the root, which is the vendored protocol definition that claim rests on. Since Tempo 2.0, Apache Parquet is the default storage format, per the linked Grafana blog post in the README. Parquet in object storage is what makes the cost argument work: columnar files compress well and object storage is cheap, so the expensive part of a tracing system disappears.

Two components sit outside the ingest path. tempo-vulture is described as Tempo's "bird themed consistency checking tool" that writes traces and queries them back in a variety of ways, which is the closest thing to an end-to-end check in the repository. tempo-cli is where utility functionality lives, with its own documentation page.

Installing Tempo from the Docker Compose example

The README does not print install commands. It points to the Get started documentation and to Deployment Examples, listing Docker Compose, Helm and Jsonnet directories under example/. The repository layout also shows example/nomad/ and example/tk/. There is no published single command in the README itself, so the honest starting point is the example directory rather than a copied snippet.

If you go the Compose route, the shape of the work is: bring up the example stack, point an OpenTelemetry collector at Tempo's ingest endpoint, then query from Grafana. Because the README does not document the port or the endpoint path, read them from the files under example/docker-compose/ before you write your collector config. Do not guess the receiver port.

For a Helm install, the example tree contains example/helm/. The Makefile shows the release tooling the project itself uses, including a VERSION file read at build time and a goreleaser target, but that is the maintainers' build path, not a user install path:

make help
make build

Running make help prints the target list generated from the Makefile's own comments, which is the fastest way to see what the repository can build locally. What you should see is a usage block listing targets with their descriptions.

TraceQL metrics is experimental, and that matters

The README labels TraceQL metrics an "experimental feature in Grafana Tempo that creates metrics from traces". The mechanism: a metric query extends a trace query by applying a function to its results, letting you aggregate any TraceQL query by any dimension present in your spans, the same way LogQL metric queries build metrics from logs.

Experimental is not a marketing qualifier here. It means the API and behaviour can change between releases, so building dashboards that depend on it carries upgrade risk. If your alerting runs on TraceQL metrics, a version bump is a potential incident. Treat that feature as something to evaluate rather than something to standardise on.

The second limitation is architectural and permanent: Tempo is a backend. It has no tracing UI of its own. The README's answer to that is the Traces Drilldown app (formerly Explore Traces), a separate repository in the Grafana Explore suite, described as "queryless and intuitive" and aimed at people who do not want to write TraceQL. That app is a different project with its own release cycle. Choosing Tempo means choosing Grafana as your query surface, and the README notes that UI issues should be filed against Grafana, not Tempo.

Tempo against Jaeger, and what actually differs

Jaeger is the obvious comparison because Tempo ingests Jaeger-format batches and the repository vendors jaeger-idl. The difference is where the data lives and what queries it. A classic Jaeger deployment stores traces in a database with an index, typically Cassandra or Elasticsearch, which is why running it at volume means running and sizing a stateful cluster. Tempo writes Parquet to object storage and keeps no such index, which is the whole cost argument.

The price of that choice is query flexibility. Without an index, you cannot do arbitrary full-text search across every span attribute the way an indexed store allows. TraceQL is the interface, and it is designed around traces-first queries rather than general search. If your workflow is "find me every trace containing this string in any tag", Tempo is the wrong tool and an indexed backend is the right one.

A second difference is breadth. Tempo is one component of a Grafana stack, and its value compounds with Prometheus and Loki present. Jaeger is closer to self-contained. If you have no Grafana and no intention of adding it, adopting Tempo means adopting a stack, not a service.

Licence, upgrade cost and release lines

Tempo is distributed under AGPL-3.0-only, and the README points to LICENSING.md for Apache-2.0 exceptions. That is a copyleft licence with a carve-out file attached, and the carve-out is the part that decides whether your use is covered. Read LICENSING.md rather than the one-line licence summary before you ship Tempo inside a product. This is not legal advice and the repository is the only authority on what those exceptions cover.

The upgrade picture is mixed. Three tags appear in the recent release list: v3.1.0-rc.1 (a release candidate dated 2026-09-17), v3.0.3 and v2.10.8 (both dated 2026-08-13). The v2.10.8 tag landing on the same day as v3.0.3 means the 2.x line is still receiving releases, which is relevant if you are on 2.x and not ready to move. The last push to the default branch was on 2026-09-22. The repository is not archived.

Upgrade cost concentrates in two places: the experimental TraceQL metrics surface, and the storage format history. Tempo 2.0 changed the default storage format to Parquet, so any deployment predating that has a migration behind it. The repository keeps a CHANGELOG.md at the root and a .chloggen/ directory, which is where per-release entries are collected before a release, so the changelog is the file to read before bumping a version.

Editorial conclusion

Adopt Tempo if you already run Grafana and want trace storage that costs you an object storage bucket rather than a search cluster, and if you accept that TraceQL is the query surface. Do not adopt it if you need a self-contained tracing UI with no Grafana, or if you want to keep traces in a database you already operate. Before you commit, read LICENSING.md for the Apache-2.0 exceptions to the AGPL-3.0-only licence, and confirm which release line you are installing, because v3.1.0-rc.1 is a release candidate while v3.0.3 and v2.10.8 are the dated stable tags.

Frequently asked questions

Official sources

1. grafana/tempo on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases