Contributing to Uptrace

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

Database

The database schemaContributing - 图1open 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 is listening on 2 ports:

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

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

OTLP

Uptrace accepts data from OpenTelemetryContributing - 图3open in new window using OpenTelemetry protocol (OTLP). Uptrace implements OTLP gRPC for traces in pkg/tracing/otlp_trace_grpc.goContributing - 图4open 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:

  1. clickhouse-client -q "CREATE DATABASE uptrace"

Step 2. Build Uptrace UI:

  1. make uptrace-vue

Step 3. Start Uptrace:

  1. go run cmd/uptrace/main.go serve

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

Uptrace will monitor itself using OpenTelemetry Go distroContributing - 图5open in new window 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:

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

TO learn about available commands:

  1. go run cmd/uptrace/main.go help

Running Uptrace UI

You can also start the UI locally:

  1. cd vue
  2. pnpm install
  3. pnpm serve

And open http://localhost:19876