Contributing to Uptrace

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

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.
  • span_system_minutes and span_system_hours contain pre-aggregated data from spans_index table for each span system, for example, http:service_name or db:postgresql.
  • span_service_minutes and span_service_hours contain pre-aggregated data for each service name.
  • span_host_minutes and span_host_minutes contain pre-aggregated data for each host name.

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.goopen in new window and that is where you can start exploring Uptrace code.

OTLP

Uptrace accepts data from OpenTelemetryopen in new window using OpenTelemetry protocol (OTLP). Uptrace implements OTLP gRPC for traces in pkg/tracing/otlp_trace_grpc.goopen in new window. It is also a good entry point to start working on Uptrace.

Compiling Uptrace collector

To compile and run Uptrace locally, you need Go 1.18 and ClickHouse 21.11+.

Step 1. Create uptrace ClickHouse database:

clickhouse-client -q "CREATE DATABASE uptrace"

Step 2. Build Uptrace UI:

make uptrace-vue

Step 3. Start Uptrace:

go run cmd/uptrace/main.go serve

Step 4. 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 build 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: