Getting started with Uptrace and OpenTelemetry

To get started with Uptrace, you need to:

  1. Create a ClickHouse database.
  2. Install Uptrace binary.
  3. Start sending data using OpenTelemetry distro for Uptrace.
  4. Enjoy!


Dockeropen in new window example can get you started with a single command.


Uptrace requires ClickHouse database to store telemetry data. After installingopen in new window ClickHouse, you can create uptrace database like this:

clickhouse-client -q "CREATE DATABASE uptrace"

When started, Uptrace will connect to the ClickHouse database specified in uptrace.yml config and will automatically create required tables and views.



Uptrace provides DEB and RPM packages for Linux amd64/arm64 systems. After installing the approriate package, you will have:

  • Uptrace binary at /usr/bin/uptrace.
  • Uptrace config at /etc/uptrace/uptrace.yml.
  • Systemd service at /lib/systemd/system/uptrace.service.
  • Environment file used by the systemd service at /etc/uptrace/uptrace.conf.

To check the status of Uptrace service:

sudo systemctl status uptrace

To restart Uptrace:

sudo systemctl restart uptrace

To view Uptrace logs:

sudo journalctl -u uptrace -f


To install Debian package, run the following command replacing 1.0.0 with the desired version and amd64 with the desired architecture:

sudo dpkg -i uptrace_1.0.0_amd64.deb


To install RPM package, run the following command replacing 1.0.0 with the desired version and x86_64 with the desired architecture:

sudo rpm -ivh uptrace-1.0.0-1.x86_64.rpm


Alternatively, instead of installing DEB or RPM packages, you can downloadopen in new window a pre-compiled binary and install Uptrace manually.


Download Linux binary:

wget -O ./uptrace
chmod +x ./uptrace

Download Uptrace config:


Start Uptrace:

./uptrace --config=uptrace.yml serve


Download MacOS binary:

wget -O uptrace{{ uptrace.version }}/uptrace_darwin_amd64
chmod +x uptrace

Download Uptrace config:


Start Uptrace:

./uptrace --config=uptrace.yml serve

You may need to update ClickHouse connection string in uptrace.yml using ch.dsn option.


For pre-compiled binaries for other platforms, check GitHub Releasesopen in new window.

Start sending data

To start sending data, you can use OpenTelemetry distros that pre-configured to work with Uptrace. Uptrace uses OpenTelemetry protocol (OTLP) to receive telemetry data such as spansopen in new window, metricsopen in new window, and logs. As a transport protocol, OTLP can use gRPC (OTLP/gRPC) or HTTP (OTLP/HTTP).

Uptrace supports OTLP/gRPC on the port 14317 and OTLP/HTTP on the port 14318. The port is specified in the Uptrace DSN that you will receive after installing Uptrace, for example:


OpenTelemetry GoOTLP/gRPC14317
OpenTelemetry .NETOTLP/gRPC14317
OpenTelemetry PythonOTLP/gRPC14317
OpenTelemetry Node.jsOTLP/HTTP14318
OpenTelemetry RubyOTLP/HTTP14318
OpenTelemetry JavaOTLP/HTTP14317
OpenTelemetry PHPOTLP/HTTP14318

For example, to run basic Go exampleopen in new window, you need to use OTLP/gRPC and port 14317:

UPTRACE_DSN=http://<token>:localhost:14317/<project_id> go run .

But to run basic Node.js exampleopen in new window, you need to use OTLP/HTTP and port 14318:

UPTRACE_DSN=http://<token>:localhost:14318/<project_id> node main.js

GitHub notifications

To get notified about a new Uptrace release, star the uptrace/uptraceopen in new window repo and subscribe to notifications.

  1. Click on "Watch" -> "Custom".
  2. Select "Releases".
  3. Click on "Apply" to save changes.

GitHub notifications

What's next?

Next, you can browse instrumentationsopen in new window to find examples for your framework and libraries or learn about OpenTelemetry APIopen in new window to create your own instrumentations.

Last Updated: