Uptrace Configuration

You can tweak Uptrace settings and change the generated ClickHouse database schema using a single YAML config file.

You can always find the latest version of the config at GitHubopen in new window.

Config location

You can specify the location of Uptrace config using a CLI arg:

uptrace --config=/path/to/uptrace.yml serve

Or using an env variable:

UPTRACE_CONFIG=/path/to/uptrace.yml uptrace serve

When you don't explicitly specify the config location, Uptrace will check for a config in the following locations:

  1. ./uptrace.yml
  2. ./config/uptrace.yml
  3. /etc/uptrace/uptrace.yml

ClickHouse credentials

You can configure ClickHouse database credentials in the config:

  addr: localhost:9000
  user: default
  database: uptrace

To use TLS connections, you need to enable a secure TCP port in ClickHouse config:

<?xml version="1.0" ?>

And then use the new port in the Uptrace config:

  addr: localhost:9440
  user: default
  database: uptrace

    insecure_skip_verify: true

ClickHouse schema

The options described below allow to change the ClickHouse schema generated by Uptrace. For changes to take effect, you need to reset the ClickHouse database:

uptrace ch reset


You can configure the compression method used in ClickHouse tables like this:

  # Compression codec, for example, LZ4, ZSTD(3), or Default.
  compression: ZSTD(3)


You can replicate data by using Replicated* table engines, for example, ReplicatedMergeTree:

  # Whether to use ReplicatedMergeTree instead of MergeTree.
  replicated: true


To use distributed tables, specify the name of the ClickHouse cluster:

  # Cluster name for Distributed tables and ON CLUSTER clause.
  cluster: my_uptrace_cluster

And then reset the database:

uptrace ch reset

Uptrace should create distributed tables like this one:

CREATE TABLE spans_index_dist ON CLUSTER my_uptrace_cluster AS spans_index
ENGINE = Distributed(my_uptrace_cluster, currentDatabase(), spans_index)

S3 storage

ClickHouse supports S3-like storage out-of-the-box and allows to move data to S3 using TTL statements on tables, for example:

CREATE TABLE test (...)
TTL toDate(time) + INTERVAL 30 DAY DELETE,
    toDate(time) + INTERVAL 10 DAY TO VOLUME 's3'

First, you need to create a storage policy in ClickHouse by editing config.xml:

        <!-- <keep_free_space_bytes>2147483648</keep_free_space_bytes> -->





Then, use the following commands to update tables TTL to start moving data to the S3 volume:

# spans_index table: move data to S3 after 10 days
uptrace ch_schema ttl_move --table=spans_index --after="14 DAY" --storage=tiered

# spans_data table: move data to S3 after 3 days
uptrace ch_schema ttl_move --table=spans_data --after="5 DAY" --storage=tiered

Managing projects

Uptrace allows you to configure as many projects as you want in the YAML config:

  - id: 1
    name: Uptrace
    # Token grants write access to the project. Keep a secret.
    token: project1_secret_token
    # A list of attributes to pin on the Overview page.
      - service.name
      - host.name
      - deployment.environment

Managing users

By default, Uptrace allows anyone to use UI to view data. To require authentication, uncomment the following section in the config:

    - username: uptrace
      password: uptrace

You can also connect Uptrace to Keycloak, Cloudflare, and Google.


First, generate a self-signed certificate replacing localhost with your domain:

openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout uptrace.key -out uptrace.crt -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost"

Then, add the certificate to the list of trusted certificates:

sudo cp uptrace.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Finally, configure Uptrace to start using the certificate you just created:

    addr: ':14317'
      cert_file: config/tls/uptrace.crt
      key_file: config/tls/uptrace.key
      #ca_file path/to/ca_file

  # OTLP/HTTP and Uptrace API with UI.
    addr: ':14318'
      cert_file: config/tls/uptrace.crt
      key_file: config/tls/uptrace.key
      #ca_file path/to/ca_file

Don't forget to restart Uptrace:

sudo systemctl restart uptrace

SQLite and PostreSQL

By default, Uptrace uses SQLite database to store metadata:

  driver: sqlite
  # Uptrace automatically creates SQLite database file in the current working directory.
  # Make sure the directory is writable by Uptrace process.
  dsn: 'file:uptrace.sqlite3?_pragma=foreign_keys(1)&_pragma=busy_timeout(1000)'

But you can also configure Uptrace to use PostgreSQL, for exampleopen in new window:

  driver: postgres
  # Connection string for PostgreSQL database. For example:
  # postgres://<user>:<password>@<host>:<port>/<database>?sslmode=disable
  # See https://bun.uptrace.dev/postgres/
  dsn: postgres://uptrace:uptrace@localhost:5432/uptrace?sslmode=disable
Last Updated: