Contributing to Uptrace
Uptrace is a distributed tracing tool that collects data using OpenTelemetry and stores it in ClickHouse database.
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 usingspans_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 bytrace_id
thanspans_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.
OTLP
Uptrace accepts data from OpenTelemetry using OpenTelemetry protocol (OTLP). Uptrace implements OTLP gRPC for traces in pkg/tracing/otlp_trace_grpc.go. 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