Getting started with Uptrace and OpenTelemetry

Getting started with Uptrace and OpenTelemetry

Uptraceopen in new window is a distributed tracing tool that uses OpenTelemetry to collect data and ClickHouse database to store it. It is a self-hosted version of Uptrace Cloudopen in new window.

To get started with Uptrace, you need to:

Create ClickHouse database.
Install Uptrace binary.
Start sending data using OpenTelemetry distro for Uptrace.

ClickHouse

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.

Installation

Packages

Uptrace provides DEB and RPM packages for Linux amd64/arm64 systems. After installing an 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

DEB

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

wget https://github.com/uptrace/uptrace/releases/download/v0.2.13/uptrace_0.2.13_amd64.deb
sudo dpkg -i uptrace_0.2.13_amd64.deb

RPM

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

wget https://github.com/uptrace/uptrace/releases/download/v0.2.13/uptrace-0.2.13-1.x86_64.rpm
sudo rpm -ivh uptrace-0.2.13-1.x86_64.rpm

Binaries

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

Linux

Download Linux binary:

wget -O ./uptrace https://github.com/uptrace/uptrace/releases/download/v0.2.13/uptrace_linux_amd64
chmod +x ./uptrace

Download Uptrace config:

wget https://raw.githubusercontent.com/uptrace/uptrace/master/config/uptrace.yml

Start Uptrace:

./uptrace --config=uptrace.yml serve

MacOS

Download MacOS binary:

wget -O uptrace https://github.com/uptrace/uptrace/releases/download/v0.2.13/uptrace_darwin_amd64
chmod +x uptrace

Download Uptrace config:

wget https://raw.githubusercontent.com/uptrace/uptrace/master/config/uptrace.yml

Start Uptrace:

./uptrace --config=uptrace.yml serve

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

Other

Check GitHub Releasesopen in new window for pre-compiled binaries for other platforms.

Start sending data

To start receiving data, you need to install OpenTelemetry distroopen in new window configured to work with Uptrace. Uptrace uses OpenTelemetry protocol (OTLP) to receive telemetry data, for example, spansopen in new window, errors, 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:

# OTLP/gRPC
UPTRACE_DSN=http://project2_secret_token@localhost:14317/2
# OTLP/HTTP
UPTRACE_DSN=http://project2_secret_token@localhost:14318/2

Client	Protocol	Port
uptrace-goopen in new window	OTLP/gRPC	14317
uptrace-dotnetopen in new window	OTLP/gRPC	14317
uptrace-pythonopen in new window	OTLP/gRPC	14317
uptrace-nodeopen in new window	OTLP/HTTP	14318
uptrace-rubyopen in new window	OTLP/HTTP	14318

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

UPTRACE_DSN=http://<project_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://<project_token>:localhost:14318/<project_id> node main.js

You can also try tutorials for the most popular frameworks:

OpenTelemetry Collector

If you are already using OpenTelemetry Collectoropen in new window, you can configure it to send data to Uptrace:

gRPC
HTTP

exporters:
  otlp:
    endpoint: http://localhost:14317
    tls:
      insecure: true
    headers:
      uptrace-dsn: 'http://<project_token>:localhost:14317/<project_id>'

exporters:
  otlphttp:
    endpoint: http://localhost:14318
    tls:
      insecure: true
    headers:
      uptrace-dsn: 'http://<project_token>:localhost:14318/<project_id>'

GitHub notifications

You can enable GitHub notificationsopen in new window to receive an email when a new Uptrace version is released.

You can also consider subscribing to the newsletteropen in new window to receive latest updates about OpenTelemetry and Uptrace.

What’s next?

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