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 as a CLI arg:

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

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

Uptrace uses the ClickHouse database specified in the config:

  # Connection string for ClickHouse database. For example:
  # clickhouse://<user>:<password>@<host>:<port>/<database>?sslmode=disable
  # See https://clickhouse.uptrace.dev/guide/golang-clickhouse.html#options
  dsn: 'clickhouse://default:@localhost:9000/uptrace?sslmode=disable'

ClickHouse schema

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

uptrace ch reset


To change ClickHouse compression for all columns:

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


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

That will cause Uptrace to create distributed tables next time the database is resetted:

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 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="10 DAY" --storage=tiered

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

Managing projects and users

Uptrace allows you to create as many projects as you want. All you need to do is to drop few lines in the 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

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

  - id: 1
    username: uptrace
    password: uptrace


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"

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
Last Updated: