Tempo — Kubernetes distributed-tracing server
This example compiles a small, real stack — a Grafana Tempo distributed-tracing
server — from one Developer-authored Aggregate to Kubernetes via Workload
synthesis on the official grafana/tempo image, in its single-binary shape.
Tempo is a trace backend: it receives spans over the OpenTelemetry protocol (and other tracing wire formats), stores them in a trace object store, and answers trace-lookup and search queries over its HTTP API. In the single-binary shape every Tempo subsystem — distributor, ingester, querier, compactor — runs inside one process backed by a local trace store, so the whole server is one stateful workload. An instrumented application pushes spans to Tempo’s OTLP receiver; a dashboards server reads them back over the query API.
Files
| File | Role |
|---|---|
aggregate.yaml | Developer intent: a single tracing component (core/observability/tempo) keeping traces for seven days. |
manifest.yaml | Maps the component type to the synthesized Tempo Recipe (tempo). |
release.yaml | Operator record for the Kubernetes target: the server compute and trace-store volume size. |
What it demonstrates
- One authoring surface. A single Aggregate is the source of truth for what Tempo is; the Manifest says how to realize it.
- A single-binary trace backend. The synthesized Recipe renders Tempo as one
StatefulSetwith a per-replica data volume, oneConfigMapcarrying the Tempo config, and aClusterIPandHeadlessServiceexposing the trace receivers and the HTTP query API — a single self-contained workload. - Developer-set retention. The developer’s
retention_periodflows into the in-process compactor, which deletes stored trace blocks once they age past it. - An exported ingestion contract. The component exports its OTLP gRPC
receiver host and port through the
usestopology, so a trace producer wires to it and pushes spans there. - Reproducible images. The Recipe pins the Tempo server image tag from
infra.engine_versionso the rendered workload references a pinned version.
Scaffold the example
You can build this example with the commands below, or have your AI assistant build it for you.
Write the example into a new folder named after it:
aggrega scaffold --example tempo-tracingIt then prints the commands to run next. The first changes into the new folder:
cd tempo-tracingBuild
This workspace carries no .aggrega-config.yaml, so the standard-library
entities resolve from the hub registry, hub.aggrega.ai, and no catalog flag is
needed; --auto-pull writes the lockfile a fresh clone lacks during the build:
aggrega build --release release.yaml --auto-pullRendered artifacts land under dist/. The synthesized target needs no external
chart fetch — the Recipe renders the official image directly into a StatefulSet,
Services, and a data volume.
With an AI assistant
An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.
Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `tempo-tracing` folder yet, call the `scaffold` tool once with `example` set to `tempo-tracing` and no `dir`: it writes the example into a new `tempo-tracing` folder. Then call the `build` tool with `workspace_root` set to `tempo-tracing`, `release` set to `release.yaml`, `auto_pull` set to true and `write` set to true. Tell me which files the build wrote; they are under `tempo-tracing/dist/`.What renders
The build emits the Tempo server as four Kubernetes objects:
- a
StatefulSet— the single-binary Tempo process, with its trace store on a per-replica persistent volume, - a
ConfigMap— the Tempo configuration, - a
ClusterIP Service— exposing the OTLP gRPC receiver on 4317, the OTLP HTTP receiver on 4318, and the HTTP query API on 3200, - a
Headless Service— the StatefulSet’s stable network identity, exposing the same ports.
The Tempo image tag is pinned from infra.engine_version, so the workload
references a pinned image tag.