Contributing to Uptrace

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

• Source code
• Compiling Uptrace collector
• Compiling Uptrace UI
• Database
• Routes

Source code

To obtain Uptrace source code:

git clone git@github.com:uptrace/uptrace.git

Then you must initialize Git submodules:

git submodule update --init --recursive

The repository contains a Docker compose config that starts all Uptrace dependencies such as PostgreSQL and ClickHouse databases:

docker-compose up -d

Compiling Uptrace collector

Step 1. Build Uptrace UI:

make uptrace-vue

Step 2. Start Uptrace using the development config at config/uptrace.yml:

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

Step 3. 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

Compiling Uptrace UI

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

cd vue
pnpm install
pnpm serve

Then you can open http://localhost:19876 to view the UI.

Database

The database schema 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.

Routes

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.go and that is where you can start exploring Uptrace code.