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
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:
./uptrace.yml
./config/uptrace.yml
/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