Installing Uptrace
To install Uptrace on your computer, you need to:
- Create a ClickHouse database to store telemetry data.
- Create a PostgreSQL database to store users and projects.
- Install Redis database for caching.
- Install the Uptrace binary.
- Start sending data using the OpenTelemetry protocol.
- Enjoy! 🎉
Instead of installing everything manually, you can also try the following deployment methods:
- Docker can get you started with a single command.
- Ansible playbook is ideal for installing Uptrace on bare metal servers.
- Kubernetes Helm chart works best if you already have a Kubernetes cluster.
Hardware Requirements
Spans and Logs | Time Series | Hardware Requirements |
---|---|---|
30 TB | 2 million | 24 vCPU, 48GB RAM, 1TB SSD, 6TB HDD |
50 TB | 3 million | 32 vCPU, 96GB RAM, 2TB SSD, 12TB HDD |
100 TB | 6 million | 64 vCPU, 160GB RAM, 4TB SSD, 20TB HDD |
500 TB | 30 million | 192 vCPU, 576GB RAM, 8TB SSD, 100TB HDD |
Configuration
All Uptrace configuration is done with a single YAML file that can be created using the Uptrace binary:
uptrace --config=/path/to/config.yml config create
You can then specify the config file location when starting Uptrace:
uptrace --config=/path/to/config.yml serve
See Configuration for more details.
ClickHouse
Uptrace requires a ClickHouse database to store telemetry data such as traces, logs, and metrics. ClickHouse is an open-source columnar database management system designed to handle large amounts of data and execute complex analytical queries with low latency.
After installing ClickHouse, you can create the uptrace
database like this:
clickhouse-client -q "CREATE DATABASE uptrace"
On startup, Uptrace connects to the ClickHouse database specified in the uptrace.yml
configuration file and automatically creates the required tables and views.
# uptrace.yml
ch_cluster:
shards:
- replicas:
- addr: localhost:9000
user: default
password:
database: uptrace
PostgreSQL
Uptrace also requires a PostgreSQL database to store metadata such as metric names and alerts. Typically, the PostgreSQL database requires only a few megabytes of disk space.
After installing PostgreSQL, you can create the database like this:
sudo -u postgres psql
postgres=# CREATE DATABASE uptrace;
postgres=# CREATE USER uptrace WITH ENCRYPTED PASSWORD 'uptrace';
postgres=# GRANT ALL PRIVILEGES ON DATABASE uptrace TO uptrace;
postgres=# \c uptrace
postgres=# GRANT ALL ON SCHEMA public TO uptrace;
On startup, Uptrace connects to the PostgreSQL database specified in the uptrace.yml
configuration file and automatically creates the required tables and views.
# uptrace.yml
pg:
addr: localhost:5432
user: uptrace
password: uptrace
database: uptrace
Redis
Uptrace requires Redis for caching query results and session management. Redis is a mandatory dependency that significantly improves query performance and reduces database load.
After installing Redis, you must configure Uptrace to connect to it by adding the following to your uptrace.yml
configuration file:
# uptrace.yml
redis_cache:
# Single Redis server
addr: localhost:6379
# Authentication (if required)
username: ''
password: 'your_redis_password'
db: 0
# Connection timeouts
dial_timeout: 5s
read_timeout: 3s
write_timeout: 3s
Installation
Packages
Uptrace provides DEB and RPM packages for Linux amd64/arm64 systems. After installing the appropriate package, you will have:
- Uptrace binary at
/usr/bin/uptrace
- Uptrace config at
/etc/uptrace/config.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 the 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 the Debian package, run the following command, replacing 2.0.0
with the desired version and amd64
with the desired architecture:
wget https://github.com/uptrace/uptrace/releases/download/v2.0.0/uptrace_2.0.0_amd64.deb
sudo dpkg -i uptrace_2.0.0_amd64.deb
RPM
To install the RPM package, run the following command, replacing 2.0.0
with the desired version and x86_64
with the desired architecture:
wget https://github.com/uptrace/uptrace/releases/download/v2.0.0/uptrace-2.0.0-1.x86_64.rpm
sudo rpm -ivh uptrace-2.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 the Linux binary:
wget -O ./uptrace https://github.com/uptrace/uptrace/releases/download/v2.0.0/uptrace_linux_amd64
chmod +x ./uptrace
Create the Uptrace config:
./uptrace --config=/path/to/config.yml config create
Start Uptrace:
./uptrace --config=/path/to/config.yml serve
macOS
Download the macOS binary:
wget -O uptrace https://github.com/uptrace/uptrace/releases/download/v2.0.0/uptrace_darwin_amd64
chmod +x uptrace
Create the Uptrace config:
./uptrace --config=/path/to/config.yml config create
Start Uptrace:
./uptrace --config=/path/to/config.yml serve
Windows
Download the Windows binary:
curl -O uptrace_windows_amd64.exe https://github.com/uptrace/uptrace/releases/download/v2.0.0/uptrace_windows_amd64.exe
Create the Uptrace config:
uptrace_windows_amd64.exe --config=/path/to/config.yml config create
Start Uptrace:
uptrace_windows_amd64.exe --config=/path/to/config.yml serve
Other
For pre-compiled binaries for other platforms, check GitHub Releases.
Start Sending Data
To start sending data, you can use OpenTelemetry distributions that are pre-configured to work with Uptrace. Uptrace uses the 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 port 4317
and OTLP/HTTP on port 4318
. Both ports are specified in the Uptrace DSN that you will receive after installing Uptrace.
What's Next?
Next, learn how to configure Uptrace for your needs.