Which receiver protocol should I use?

OTLP is the modern default and what OpenTelemetry SDKs and the OpenTelemetry Collector speak natively, so pick it for any new instrumentation. Jaeger and Zipkin exist for compatibility with existing instrumentation already emitting those formats; you don't need all three unless you're actually receiving traces in more than one format.

What does the storage backend actually store?

Tempo's storage.trace backend is where completed trace blocks land after they're flushed from the ingester, it's the durable store trace queries read from. Local disk works for a single-node setup or testing, while S3, GCS, and Azure Blob are the common choices for anything meant to scale or survive node loss.

What is metrics_generator for?

When enabled, Tempo derives Prometheus-style metrics (like span-based RED metrics and service graphs) directly from the trace spans it ingests and remote-writes them to a metrics backend, letting you get request-rate/error/duration dashboards without instrumenting metrics separately from traces.

Is this a complete, production-ready tempo.yaml?

It covers the server, distributor.receivers, storage.trace, and metrics_generator sections, which is enough to get a working single-binary Tempo instance receiving and storing traces. Larger deployments typically also tune ingester, compactor, and querier settings, which this tool doesn't attempt to model.

Tempo Config Generator - Build a Grafana Tempo Config YAML

Overview

Introduction

A Tempo config's distributor.receivers and storage.trace sections nest several levels deep and change shape entirely depending on which protocol and storage backend you pick, easy to get wrong from memory.

This tool builds that config from a form: choose a trace receiver protocol and its ports, pick a storage backend and fill in its fields, and optionally turn on the metrics-generator, all rendered as correctly nested YAML.

What Is Tempo Config Generator?

A visual builder for a Grafana Tempo configuration YAML, covering the server block, a distributor.receivers entry for OTLP, Jaeger, or Zipkin, a storage.trace backend (local, S3, GCS, or Azure), and an optional metrics_generator block.

It mirrors Tempo's own config structure so the output can be used as a starting config.yaml passed to the tempo binary with -config.file.

How Tempo Config Generator Works

Based on your chosen receiver protocol, the distributor.receivers block is built with that protocol's specific nested keys, OTLP nests grpc/http endpoints under protocols, Jaeger nests thrift_http, and Zipkin is a flat endpoint.

The storage.trace block always sets backend to your chosen option and then adds that backend's specific block (local.path, s3.bucket/endpoint, gcs.bucket_name, or azure.container_name/storage_account_name). If metrics-generator is enabled, a metrics_generator block is appended with span-metrics and service-graphs processors and a remote_write target.

When To Use Tempo Config Generator

Use it when standing up a new Tempo instance to receive traces from an OpenTelemetry Collector, Jaeger client, or Zipkin-compatible tracer.

It's also useful for quickly sketching what an S3 or Azure storage.trace block looks like when moving an existing local-disk Tempo instance to durable object storage.

Often used alongside OpenTelemetry Collector Config Generator, Prometheus Config Generator and Grafana Dashboard Generator.

Features

Advantages

Covers all three common trace protocols and all four common storage backends with each one's exact nested key names, avoiding a common source of Tempo startup failures.
Validates that receiver ports are numeric and in range, and that each storage backend's required fields are filled in, before generating output.
Includes a ready-to-adjust metrics_generator block with the two most common processors (span-metrics, service-graphs) instead of an empty stub.

Limitations

Only models one receiver protocol at a time; a Tempo instance accepting multiple protocols simultaneously needs the additional protocol blocks merged in manually.
Doesn't cover ingester, compactor, or querier tuning, only the receiver, storage, and metrics-generator sections.
The metrics_generator remote_write target defaults to a local placeholder URL; you'll need to point it at your actual Prometheus or Mimir remote-write endpoint.

Examples

An OTLP receiver backed by local disk

Input

receiver: OTLP (grpc 4317, http 4318), storage: local (/var/tempo/traces), metrics_generator: disabled

Output

server:
  http_listen_port: 3200

distributor:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
        http:
          endpoint: 0.0.0.0:4318

storage:
  trace:
    backend: local
    local:
      path: /var/tempo/traces

metrics_generator_enabled: false

Both OTLP protocol endpoints are emitted under distributor.receivers.otlp.protocols, and storage.trace points at the local path.

Best Practices & Notes

Best Practices

Default to OTLP unless an existing system specifically requires Jaeger or Zipkin ingestion, since OTLP is the direction the tracing ecosystem has standardized on.
Move off local storage before relying on Tempo for anything beyond a quick test, since local disk ties trace data to a single node and doesn't survive that node's loss.
Enable metrics-generator if you want RED metrics and service graphs derived from traces without a separate metrics-instrumentation effort, but budget for the extra write load it generates.

Developer Notes

The generator is a pure string-building function emitting fixed 2-space YAML with no YAML library dependency; ports are validated against a 1-65535 numeric range and each storage backend branch requires only that backend's specific fields. The metrics_generator block, when enabled, is a representative subset (registry, processor, storage, remote_write) intended as a starting point, not an exhaustive rendering of every metrics-generator option.

Tempo Config Generator Use Cases

Bootstrapping a single-binary Tempo instance's config to start receiving traces from an OpenTelemetry Collector
Migrating an existing Tempo instance from local disk to S3, GCS, or Azure Blob storage
Enabling metrics-generator to get span-derived RED metrics and service graphs from existing trace data

Common Mistakes

Configuring an OTLP receiver but forgetting the OpenTelemetry Collector or SDK is still pointed at the old Jaeger/Zipkin port instead of the new OTLP one.
Leaving storage backend as local for a production deployment and losing trace history when that node is replaced.
Enabling metrics_generator without updating the remote_write URL, so generated metrics are pushed to a placeholder endpoint that doesn't exist.

Tips

Use the OpenTelemetry Collector Config Generator to build a collector config that exports traces to this Tempo instance's OTLP receiver.
Use the Grafana Dashboard Generator afterward to build panels querying the RED metrics Tempo's metrics-generator produces once it's wired to a remote_write target.

Tempo Config Generator