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

Documentationbreadcrumb arrow Grafana Tempobreadcrumb arrow Set up for tracingbreadcrumb arrow Set up Tempobreadcrumb arrow Command line flags
Open source

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

FlagDescriptionDefault
--versionPrint this build’s version information and exitfalse
--mutex-profile-fractionOverride default mutex profiling fraction0
--block-profile-thresholdOverride default block profiling threshold0
--config.fileConfiguration file to load
--config.expand-envWhether to expand environment variables in config filefalse
--config.verifyVerify configuration and exitfalse

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).

FlagDescriptionDefault
--targetTarget module to runall

Valid target values:

TargetDescription
allMonolithic mode. Runs all components in a single process.
distributorReceives and distributes trace data to downstream components.
metrics-generatorGenerates metrics from ingested trace data.
querierQueries the backend storage for traces and metrics.
query-frontendProvides search API and splits queries for parallelism.
block-builderConsumes data from Kafka and writes blocks to backend storage.
backend-schedulerSchedules and coordinates backend query jobs across workers.
backend-workerExecutes query jobs assigned by the backend scheduler.
live-storeServes recently ingested data from Kafka for real-time queries.

Note

In Tempo 3.0, the ingester, compactor, and scalable-single-binary targets were removed as part of the new Tempo architecture.

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

Authentication and multitenancy

FlagDescriptionDefault
--multitenancy.enabledSet to true to enable multitenancyfalse
--auth.enabledDeprecated. Use --multitenancy.enabled instead. Set to true to enable auth. This flag will be removed in a future release.false

HTTP and API settings

FlagDescriptionDefault
--http-api-prefixString prefix for all HTTP API endpoints""
--enable-go-runtime-metricsSet to true to enable all Go runtime metricsfalse
--shutdown-delayHow long to wait between SIGTERM and shutdown. After receiving SIGTERM, Tempo reports not-ready status via the /ready endpoint.0

Health check

FlagDescriptionDefault
--healthRun a health check against the /ready endpoint and exit. Returns exit code 0 if healthy, 1 if unhealthy.false
--health.urlURL to check when running a health checkhttp://localhost:3200/ready

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 
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

FlagDescriptionDefault
--log.levelOnly log messages with the given severity or above. Valid levels: debug, info, warn, errorinfo
--log.formatOutput log messages in the given format. Valid formats: logfmt, jsonlogfmt

Server settings

FlagDescriptionDefault
--server.http-listen-portHTTP server listen port3200
--server.grpc-listen-portgRPC server listen port9095

Memberlist settings

FlagDescriptionDefault
--memberlist.host-portHost port to connect to memberlist cluster
--memberlist.bind-portPort for memberlist to communicate on7946
--memberlist.message-history-buffer-bytesSize in bytes for the message history buffer0

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 extensively 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 
tempo --config.file=/etc/tempo/config.yaml

Start Tempo with a specific target:

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

Verify configuration without starting Tempo:

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

Print version information:

Bash 
tempo --version

Start Tempo with debug-level logging for troubleshooting:

Bash 
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 
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 
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 
tempo --config.file=/etc/tempo/config.yaml \
  --multitenancy.enabled \
  --shutdown-delay=30s

Run a health check against a custom URL:

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