Getting started with Uptrace and OpenTelemetry

To get started with Uptrace, you need to:

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

TIP

Docker example can get you started in no time with a single command. If you are using Kubernetes, you can also try Uptrace Helm chart.

• ClickHouse
• PostgreSQL
• Installation
  • Packages
  • Binaries
• Start sending data
• GitHub notifications
• What's next?

ClickHouse

Uptrace requires ClickHouse database to store telemetry data such as traces, logs, and metrics. ClickHouse is an open-source columnar database management system designed for handling large volumes of data and executing complex analytical queries with low latency.

After installing 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.

ch:
  addr: localhost:9000
  user: default
  password:
  database: uptrace

PostgreSQL

Uptrace also requires PostgreSQL database to store metadata such as metric names and alerts. Usually, the PostgreSQL database only takes few megabytes of disk space.

After installing PostgreSQL, you can create uptrace database like this:

sudo -u postgres psql "CREATE DATABASE uptrace"

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

pg:
  addr: localhost:5432
  user: uptrace
  password: uptrace
  database: uptrace

Installation

Packages

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

DEB

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

wget https://github.com/uptrace/uptrace/releases/download/v1.0.0/uptrace_1.0.0_amd64.deb
sudo dpkg -i uptrace_1.0.0_amd64.deb

RPM

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

wget https://github.com/uptrace/uptrace/releases/download/v1.0.0/uptrace-1.0.0-1.x86_64.rpm
sudo rpm -ivh uptrace-1.0.0-1.x86_64.rpm

Binaries

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

• Linux
• MacOS
• Windows

Linux

Download Linux binary:

wget -O ./uptrace https://github.com/uptrace/uptrace/releases/download/v1.0.0/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/v1.0.0/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.

Windows

Download Windows binary:

curl uptrace https://github.com/uptrace/uptrace/releases/download/v1.0.0/uptrace_windows_amd64.exe

Download Uptrace config:

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

Start Uptrace:

uptrace_windows_amd64.exe --config=uptrace.yml serve

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

Other

For pre-compiled binaries for other platforms, check GitHub Releases.

Start sending data

To start sending data, you can use OpenTelemetry distros that are pre-configured to work with Uptrace. Uptrace uses OpenTelemetry protocol (OTLP) to receive telemetry data such as traces, metrics, 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

Distro	Protocol	Port
OpenTelemetry Go	OTLP/gRPC	14317
OpenTelemetry .NET	OTLP/gRPC	14317
OpenTelemetry Python	OTLP/gRPC	14317
OpenTelemetry Rust	OTLP/gRPC	14317
OpenTelemetry Node.js	OTLP/HTTP	14318
OpenTelemetry Ruby	OTLP/HTTP	14318
OpenTelemetry Java	OTLP/HTTP	14317
OpenTelemetry PHP	OTLP/HTTP	14318
OpenTelemetry Erlang/Elixir	OTLP/gRPC	14317

For example, to run the basic Go example, you need to use OTLP/gRPC and port 14317:

UPTRACE_DSN=http://project2_secret_token@localhost:14317/2 go run .

But to run the basic Node.js example, you need to use OTLP/HTTP and port 14318:

UPTRACE_DSN=http://project2_secret_token@localhost:14318/2 node main.js

Go

Python

Ruby

Node.js

.NET

Java

Erlang

Elixir

PHP

Rust

GitHub notifications

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

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

What's next?

Next, learn how to configure Uptrace for your needs or browse available instrumentations to find examples for your framework and libraries.