This is documentation for the next version of Grafana Tempo documentation. For the latest stable release, go to the latest version.

Documentation Grafana Tempo Set up for tracing Set up Tempo Command line flags

Command line flags

Tempo provides various command-line flags to configure its behavior when starting the binary. This document serves as a reference for these flags.

Global flags

Target flag

The deployment mode is determined by the runtime configuration target, or by using the -target flag on the command line. The default target is all, which runs all components in a single process (monolithic deployment mode).

Valid target values:

Refer to the Plan your Tempo deployment documentation for information on deployment modes.

Authentication and multitenancy

HTTP and API settings

Health check

The Tempo container image uses a distroless base image that doesn’t include a shell, curl, wget, or other utilities. This means the common Docker health check pattern HEALTHCHECK CMD curl -f http://localhost:3200/ready doesn’t work.

The --health flag provides a native alternative. It doesn’t require a Tempo configuration file, so it can be used directly in a HEALTHCHECK instruction:

dockerfile Copy

HEALTHCHECK CMD ["/tempo", "--health"]

Kubernetes users typically don’t need this flag because they can configure httpGet readiness and liveness probes directly against the /ready endpoint.

Logging settings

Server settings

Memberlist settings

MCP server

Tempo includes an MCP (Model Context Protocol) server that provides AI assistants and Large Language Models (LLMs) with direct access to distributed tracing data through TraceQL queries and other endpoints.

Refer to the Model Context Protocol (MCP) Server documentation for more information.

Module configuration

You can use additional flags to configure individual Tempo modules, such as the distributor, block-builder, live-store, querier, backend-scheduler, backend-worker, and their components. These flags follow a pattern like --<module>.<setting> and are documented in the configuration file format.

Use the configuration file approach described in the Configuration documentation. The documentation has a comprehensive list of all configuration options.

Usage examples

Start Tempo with a configuration file:

Bash Copy

tempo --config.file=/etc/tempo/config.yaml

Start Tempo with a specific target:

Bash Copy

tempo --target=distributor --config.file=/etc/tempo/config.yaml

Verify configuration without starting Tempo:

Bash Copy

tempo --config.file=/etc/tempo/config.yaml --config.verify

Print version information:

Bash Copy

tempo --version

Start Tempo with debug-level logging for troubleshooting:

Bash Copy

tempo --config.file=/etc/tempo/config.yaml --log.level=debug

Use environment variable expansion in the config file, which lets you inject secrets or environment-specific values at startup:

Bash Copy

tempo --config.file=/etc/tempo/config.yaml --config.expand-env

Start the distributor component on a custom HTTP port with JSON-formatted logs, typical for a microservices deployment behind a load balancer:

Bash Copy

tempo --target=distributor \
  --config.file=/etc/tempo/config.yaml \
  --server.http-listen-port=3200 \
  --log.format=json

Start Tempo in monolithic mode with multitenancy enabled and a graceful shutdown delay of 30 seconds, allowing in-flight requests to complete during rolling updates:

Bash Copy

tempo --config.file=/etc/tempo/config.yaml \
  --multitenancy.enabled \
  --shutdown-delay=30s

Run a health check against a custom URL:

Bash Copy

tempo --health --health.url=http://localhost:3200/ready