Distributed tracing backend using OpenTelemetry and ClickHouse

Uptrace is a distributed tracing system that uses OpenTelemetry to collect data and ClickHouse
database to store it. ClickHouse is the only dependency.

⭐ Looking for a ClickHouse client? Check out

Distributed tracing, errors, and logs


  • OpenTelemetry protocol via gRPC (:14317) and HTTP (:14318)
  • Span/Trace grouping
  • SQL-like query language
  • Errors/logs support
  • Percentiles
  • Systems, services, and hostnames dashboards
  • Multiple users/projects via YAML config
  • Sampling/adjusted counts support


  • ClickHouse cluster support in the database schema
  • TLS support

Getting started

  • Docker example allows to run Uptrace with a single command.
  • Installation guide with pre-compiled binaries for Linux,
    MacOS, and Windows.

Compiling Uptrace manually

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. Reset ClickHouse database schema:

go run cmd/uptrace/main.go ch reset

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 uptrace-go OpenTelemetry
distro. 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 about available commands:

go run cmd/uptrace/main.go help

Compiling UI manually

You can also start the UI locally:

cd vue
pnpm install
pnpm serve

And open http://localhost:19876


What is the license?

The Business Source License is identical to Apache 2.0 with the only exception being that
you can’t use the code to create a cloud service. It is a more permissive license than, for example,
AGPL, because it allows private changes to the code.

You can learn more about BSL here.

Are there 2 versions of Uptrace?

Yes, having 2 separate versions allows us to have minimal number of dependencies (ClickHouse) and
keep the codebase small and fun to work with.

Is the database schema stable?

No, we are still making changes to the database schema and hoping to switch to
ClickHouse dynamic subcolumns when that
feature is available.


View Github