How grafana/tempo works
Project type and purpose
• This is Grafana Tempo, an open-source, distributed tracing backend.
• The tempodb directory is Tempo’s pluggable storage engine: it handles write-ahead logging, block encoding/decoding, compaction, indexing, and interfaces to object stores (S3, GCS, Azure, local FS).
tempodb file structure
Top-level under tempodb/:
• backend/ – implementations of object storage backends (azure, gcs, s3, local)
• encoding/ – block encoding schemas (common, v2, vparquet2/3/4)
• wal/ – write-ahead log for writes before blocks are built
• blocklist, blockselector – choose which blocks to query or compact
• compactor.go, retention.go – block merging and data retention
• tenant index – maps tenants → block metadata for fast lookups
• pool/ – resource pooling for concurrent operations
Configuration and tests accompany each sub-package.
README insights
• Tempo writes incoming traces through buffering (WAL) → encoding into Parquet blocks → stores blocks in object storage.
• Queries use a tenant index + block selector to find relevant blocks, retrieve & decode them, then reconstruct trace data.
Be as detailed as possible
• WAL → Encoder → Storage Adapter chain step by step
• Compactor polling object store, selecting blocks, merging, writing back
• How the Tenant Index is updated on writes/compactions and read on queries
• Role of the Blocklist Poller that keeps track of available blocks in each tenant