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:

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

Compression

To change ClickHouse compression for all columns:

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

Replication

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

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:

<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="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:

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

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

users:
  - id: 1
    username: uptrace
    password: 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"

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

Don't forget to restart Uptrace:

sudo systemctl restart uptrace
Last Updated: