Deploy on Linux

Thu, 28 May 2026 17:50:33 +0100

Deploy on Linux

This guide provides a step-by-step process for installing Grafana Tempo on Linux. It assumes you have access to a Linux system and the permissions required to deploy a service with network and file system access. At the end of this guide, you have a single Tempo instance deployed on a single node.

This procedure provides a test installation suitable for local development and evaluation. If you plan to use this as a starting point for a production deployment, review the configuration against your organization’s best practices for security, storage, retention, and availability. If you’re upgrading from Tempo 2.x, refer to Upgrade your Tempo installation instead.

These instructions focus on a monolithic (single-binary) installation. In single-binary mode, Tempo runs all components in one process and doesn’t require Kafka. Traces are ingested directly in-process and flushed to storage.

Before you begin

To follow this guide, you need:

OpenTelemetry telemetrygen installed to test your deployment
A running Grafana instance (refer to the installation instructions) if you want to explore traces visually

System requirements

These values are a starting point for a monolithic Tempo deployment on a single node. They are not hard minimums for every environment, and they are not production sizing recommendations.

For the Tempo host itself, start with:

4 CPUs
4–8 GB of memory

Use 16 GB of memory or more if any of the following apply:

You run additional local components on the same machine, such as Grafana, an object store, or Prometheus
You enable metrics-generator
You test moderate or high ingest rates
You increase live-trace buffering or run heavier query workloads
You want extra headroom for benchmarking or troubleshooting

Co-locating Tempo with Grafana, Prometheus, or other services on the same machine is fine for evaluation, but increases memory pressure. If memory is constrained, run Tempo on its own host.

Production sizing depends on your workload and infrastructure, including ingest rate, tenant count, query concurrency, retention, metrics-generator settings, and object store performance.

Validate sizing with your own load before using it in production.

Set up storage

This guide uses the local filesystem as the storage backend. The configuration stores the write-ahead log (WAL) at /data/tempo/wal and trace blocks at /data/tempo/blocks. Tempo also uses /var/tempo at runtime for the live store and internal caches.

Create the data directories:
Bash
```
sudo mkdir -p /data/tempo /var/tempo
```
Set the directory owner to the tempo user (created by the deb package):
Bash
```
sudo chown -R tempo /data/tempo /var/tempo
```

Local storage is suitable for single-node evaluation and development. For production environments, use an object storage backend such as AWS S3, Azure Blob Storage, or Google Cloud Storage.

If you prefer to use an S3-compatible object store for local testing, refer to S3-compatible local stores for testing for setup instructions using MinIO, SeaweedFS, or rclone.

Install Tempo

For a linux-amd64 installation, run the following commands using the command line interface on your Linux machine. You need administrator privileges to do this by running as the root user or via sudo as a user with permissions to do so.

Be sure to download the correct package for your OS and architecture. Replace <TEMPO_VERSION_NUMBER> with the version you want to install, for example 3.0.0.

Download the Tempo binary. The following example downloads Tempo for the AMD64 (x86_64) processor architecture on a Linux distribution supporting deb packages:

curl -Lo tempo_<TEMPO_VERSION_NUMBER>_linux_amd64.deb \
  https://github.com/grafana/tempo/releases/download/v<TEMPO_VERSION_NUMBER>/tempo_<TEMPO_VERSION_NUMBER>_linux_amd64.deb

Install the package:

sudo dpkg -i tempo_<TEMPO_VERSION_NUMBER>_linux_amd64.deb

Optional: Verify the download against the SHA256SUMS file published on the releases page.

Create a Tempo configuration file

In the following configuration, Tempo is configured to listen on the OTLP gRPC and HTTP protocols. By default, the OpenTelemetry Collector receiver binds to localhost instead of 0.0.0.0. This example binds to all interfaces. This can be a security risk if your Tempo instance is exposed to the public internet.

Refer to the Tempo configuration documentation for explanations of the available options.

Tip
Tempo’s configuration parser is strict about YAML indentation, especially for nested blocks like storage.trace.wal.path. If Tempo fails to start, check your indentation first.

Copy the following YAML configuration to a file called tempo.yaml:

stream_over_http_enabled: true

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
    wal:
      path: /data/tempo/wal
    local:
      path: /data/tempo/blocks

usage_report:
  reporting_enabled: false

Copy tempo.yaml to the Tempo configuration directory:
Bash
```
sudo cp tempo.yaml /etc/tempo/config.yml
```

Configuration file notes

This configuration is for monolithic mode (-target=all), where all required components run in one process without Kafka. Configuration blocks such as ingest, block_builder, live_store_client, and backend_scheduler_client do not apply to monolithic mode. Don’t copy them from microservices examples. Refer to the Components by deployment mode table for the full mapping of components and configuration blocks to each mode.

The following options are common additions to this basic configuration:

Block retention

With local storage, trace blocks accumulate on disk until they exceed the configured retention period. The default is 14 days (336h). If disk space is limited, set a shorter retention using the block_retention setting in the compaction configuration.

Metrics-generator

The metrics-generator produces RED metrics (rate, errors, duration) and service graphs from incoming trace spans. It requires a Prometheus-compatible remote write target and enabling processors in the overrides block. Refer to the metrics-generator configuration and the metrics-generator documentation for setup details.

Ingestion limits

Tempo enforces default ingestion limits that may not fit every workload. If you see RATE_LIMITED, TRACE_TOO_LARGE, or LIVE_TRACES_EXCEEDED errors, you can tune these limits globally or per-tenant in the overrides configuration. Refer to Manage trace ingestion for sizing guidance.

Backend worker

The backend_worker.backend_scheduler_addr setting is omitted from this configuration. In monolithic mode, Tempo auto-configures the backend worker to connect to the scheduler on the native gRPC port (default 9095). Setting it explicitly to the HTTP port can produce noisy polling logs.

Start the Tempo service

These systemctl instructions apply to monolithic mode only. Running individual Tempo components as separate systemd services (microservices mode) is not covered here.

Use systemctl to restart the service (depending on how you installed Tempo, this may be different):
Bash
```
sudo systemctl restart tempo.service
```
You can replace restart with stop to stop the service, and start to start the service again after it’s stopped, if required.
Verify that Tempo is running:
Bash
```
systemctl is-active tempo
```
You should see the status active returned. If you don’t, check that the configuration file is correct, and then restart the service. You can also use journalctl -u tempo to view the logs for Tempo to determine if there are any obvious reasons for failure to start.
Verify that Tempo created the storage subdirectories:
Bash
```
ls /data/tempo/
```
You should see wal and blocks directories. Trace data appears in blocks after you send traces and the live store flushes them to disk, which can take 15–30 seconds.

Test your installation

To verify that traces flow through Tempo correctly, refer to Validate your local Tempo deployment.

Next steps

After you validate your Tempo deployment, consider exploring these topics:

Instrument for distributed tracing to send traces from your own applications
Configure Tempo to customize settings for your environment
Set up monitoring for Tempo to observe your Tempo instance with dashboards and alerts

Deploy Tempo using Docker Compose

Thu, 28 May 2026 17:50:33 +0100

Deploy Tempo using Docker Compose

The example directory in the Tempo repository provides a collection of docker-compose examples with different configurations. Refer to the readme in this folder for more information.

Deploy Tempo locally on Grafana Labs

Deploy on Linux

Deploy on Linux

Before you begin

System requirements

Set up storage

Install Tempo

Create a Tempo configuration file

Configuration file notes

Block retention

Metrics-generator

Ingestion limits

Backend worker

Start the Tempo service

Test your installation

Next steps

Deploy Tempo using Docker Compose

Deploy Tempo using Docker Compose