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

• Config location
• ClickHouse credentials
• ClickHouse schema
  • Retention
  • Compression
  • Replication
  • Cluster
  • S3 storage
• Managing projects
• Managing users
• Changing ports
• TLS
• Running Uptrace on multiple servers
• SQLite and PostgreSQL

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 file in the following locations:

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

When started, Uptrace logs the location of the config file it is using.

ClickHouse credentials

You can configure ClickHouse database credentials in the config:

ch:
  addr: localhost:9000
  user: default
  password:
  database: uptrace

To use TLS connections, you need to enable the secure TCP port (9440) in ClickHouse config:

<?xml version="1.0" ?>
<clickhouse>
  <tcp_port_secure>9440</tcp_port_secure>
  <openSSL>
    <server>
      <certificateFile>/etc/clickhouse-server/server.crt</certificateFile>
      <privateKeyFile>/etc/clickhouse-server/server.key</privateKeyFile>
    </server>
  </openSSL>
</clickhouse>

And then use the port in the Uptrace config:

ch:
  addr: localhost:9440
  user: default
  password:
  database: uptrace

  tls:
    # Only for self-signed certificates.
    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

Retention

You can configure data retention for spans and metrics like this:

ch_schema:
  spans:
    # Delete spans data after 30 days.
    ttl_delete: 30 DAY
    storage_policy: 'default'

  metrics:
    # Delete metrics data after 90 days.
    ttl_delete: 90 DAY
    storage_policy: 'default'

That will cause Uptrace to set TTL toDate(time) + INTERVAL 30 DAY DELETE and SETTINGS storage_policy = 'default' when creating ClickHouse tables.

Compression

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

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

Replication

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

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

Cluster

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

ch_schema:
  # 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:

<clickhouse>
  <storage_configuration>
    <disks>
      <default>
        <!-- <keep_free_space_bytes>2147483648</keep_free_space_bytes> -->
      </default>

      <s3>
        <type>s3</type>
        <endpoint>http://[BUCKET_NAME].s3.amazonaws.com/prefix/</endpoint>
        <access_key_id>TODO</access_key_id>
        <secret_access_key>TODO</secret_access_key>
        <data_cache_enabled>1</data_cache_enabled>
        <data_cache_max_size>4294967296</data_cache_max_size>
      </s3>
    </disks>

    <policies>
      <tiered>
        <move_factor>0.05</move_factor>

        <volumes>
          <default>
            <disk>default</disk>
          </default>

          <s3>
            <disk>s3</disk>
            <prefer_not_to_merge>true</prefer_not_to_merge>
            <perform_ttl_move_on_insert>0</perform_ttl_move_on_insert>
          </s3>
        </volumes>
      </tiered>
    </policies>
  </storage_configuration>
</clickhouse>

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:

projects:
  - 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.
    pinned_attrs:
      - 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:

auth:
  users:
    - username: uptrace
      password: uptrace

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

Changing ports

By default, Uptrace listens on ports 14317 (OTLP/gRPC) and 14318 (OTLP/HTTP) to not conflict with the corresponding OpenTelemetry Collector ports: 4317 and 4318.

You can change the ports in the config, for example:

listen:
  # OTLP/gRPC API.
  grpc:
    addr: ':4317'
    # tls:
    #   cert_file: config/tls/uptrace.crt
    #   key_file: config/tls/uptrace.key

  # OTLP/HTTP API and Uptrace API with Vue UI.
  http:
    addr: ':4318'
    # tls:
    #   cert_file: config/tls/uptrace.crt
    #   key_file: config/tls/uptrace.key

You can also change the Uptrace domain for Vue-powered UI:

site:
  # Overrides public URL for Vue-powered UI.
  addr: 'http://uptrace.mydomain.com'

Don't forget to restart Uptrace:

sudo systemctl restart uptrace

TLS

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:

listen:
  # OTLP/gRPC API.
  grpc:
    addr: ':14317'
    tls:
      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.
  http:
    addr: ':14318'
    tls:
      cert_file: config/tls/uptrace.crt
      key_file: config/tls/uptrace.key
      #ca_file path/to/ca_file

You can also change the Uptrace domain for Vue-powered UI: To change the domain:

site:
  # Overrides public URL for Vue-powered UI.
  addr: 'https://uptrace.mydomain.com'

Don't forget to restart Uptrace:

sudo systemctl restart uptrace

Running Uptrace on multiple servers

SQLite and PostgreSQL

By default, Uptrace uses a local SQLite database to store metadata:

db:
  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 a shared PostgreSQL database, for example:

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