Contributing to Uptrace
Uptrace is a distributed tracing tool that collects data using OpenTelemetry and stores it in ClickHouse database.
The database schema contains the following tables:
spans_indexis 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_datais an auxilary table that is used to select spans that were found using
spans_indextable. We also use it to select all spans for a trace. It contains the original untruncated data and is much faster when querying by
span_system_hourscontain pre-aggregated data from
spans_indextable for each span system, for example,
span_service_hourscontain pre-aggregated data for each service name.
span_host_minutescontain pre-aggregated data for each host name.
To ease debugging, you can configure Uptrace to log all executed queries.
By default, Uptrace accepts requests on 2 ports:
listen.grpc = :14317for gRPC requests from OpenTelemetry SDK. See OTLP below.
listen.http = :14318for 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.
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:
Step 3. Start Uptrace:
go run cmd/uptrace/main.go serve
Step 4. Open Uptrace UI at
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