Contributing to Uptrace

Uptrace is a distributed tracing tool that collects data using OpenTelemetry and stores it in ClickHouse database.


The database schemaopen in new window contains the following tables:

  • spans_index is the main table that is used for filtering and aggregating data. For best performance, we try to store each span attribute in a separate column and truncate long attributes.
  • spans_data is an auxilary table that is used to select spans that were found using spans_index table. We also use it to select all spans for a trace. It contains the original untruncated data and is much faster when querying by trace_id than spans_index table.

To ease debugging, you can configure Uptrace to log all executed queries.


By default, Uptrace accepts requests on 2 ports:

  • listen.grpc = :14317 for gRPC requests from OpenTelemetry SDK. See OTLP below.
  • listen.http = :14318 for HTTP requests from OpenTelemetry SDK and Vue.js UI.

gRPC services and HTTP routes are defined in pkg/tracing/init.goopen in new window and that is where you can start exploring Uptrace code.

Compiling Uptrace collector

To compile and run Uptrace locally, you need Go 1.22, PostgreSQL 15+, and ClickHouse 22.11+.

Step 1. Create uptrace ClickHouse database:

clickhouse-client -q "CREATE DATABASE uptrace"

Step 2. Create uptrace PostgreSQL database:

sudo -u postgres psql
postgres=# create database uptrace;
postgres=# create user uptrace with encrypted password 'uptrace';
postgres=# grant all privileges on database uptrace to uptrace;
postgres=# \c uptrace
postgres=# grant all on schema public to uptrace;

Step 3. Init Git submodules:

git submodule update --init --recursive

Step 4. Build Uptrace UI:

make uptrace-vue

Step 5. Start Uptrace:

UPTRACE_CONFIG=config/uptrace.yml go run cmd/uptrace/main.go serve

Step 6. Open Uptrace UI at http://localhost:14318

Uptrace will monitor itself using OpenTelemetry Go distro for Uptrace. To get some test data, just reload the UI few times.

You can also run Uptrace in debug mode by providing an environment variable:

DEBUG=2 go run cmd/uptrace/main.go serve

To learn more about available commands:

go run cmd/uptrace/main.go help

Running Uptrace UI

To develop UI, Uptrace uses Vue.js 2.7 and composition API. To run UI in development mode:

cd vue
pnpm install
pnpm serve

And open http://localhost:19876

Last Updated: