Getting started with Uptrace and OpenTelemetry
To get started with Uptrace, you need to:
- Create a ClickHouse database.
- Install Uptrace binary.
- Start sending data using OpenTelemetry distro for Uptrace.
- Enjoy!
TIP
Docker example can get you started with a single command.
ClickHouse
Uptrace requires ClickHouse database to store telemetry data. 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.
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
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/v{{ uptrace.version }}/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
For pre-compiled binaries for other platforms, check GitHub Releases.
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 spans, 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 Node.js | OTLP/HTTP | 14318 |
OpenTelemetry Ruby | OTLP/HTTP | 14318 |
OpenTelemetry Java | OTLP/HTTP | 14317 |
OpenTelemetry PHP | OTLP/HTTP | 14318 |
For example, to run basic Go example, 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 example, 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/uptrace repo and subscribe to notifications.
- Click on "Watch" -> "Custom".
- Select "Releases".
- Click on "Apply" to save changes.
What's next?
Next, you can browse instrumentations to find examples for your framework and libraries or learn about OpenTelemetry API to create your own instrumentations.