Installing Uptrace

To install Uptrace on your computer, you need to:

1. Create a ClickHouse database to store telemetry data.
2. Create a PostgreSQL database to store users and projects.
3. Install Redis database for caching.
4. Install the Uptrace binary.
5. Set up the databases by running migrations and seeding data.
6. Start sending data using the OpenTelemetry protocol.
7. Enjoy! 🎉

Instead of installing everything manually, you can also try the following deployment methods:

• Docker can get you started quickly with all dependencies pre-configured.
• 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

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

The command writes a random service.secret into a new file that only its owner can read (mode 0600). It does not overwrite an existing file. If you write the config by hand, set service.secret to a random value, for example from openssl rand -hex 32. Uptrace refuses to start with an empty secret or the FIXME placeholder unless service.env is dev.

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, version 26.3 or later, 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"

Uptrace connects to the ClickHouse database specified in the configuration file. Run database migrations to create the required tables and views before you start the server.

# uptrace.yml

ch_cluster:
  shards:
    - replicas:
        - addr: localhost:9000
          user: default
          password:
          database: uptrace

PostgreSQL

Uptrace also requires a PostgreSQL database, version 15 or later, 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;

Uptrace connects to the PostgreSQL database specified in the configuration file. Run database migrations to create the required tables before you start the server.

# uptrace.yml

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

Redis

Uptrace requires Redis. It keeps its task queues, rate limits, and distributed locks in Redis, and caches query results there. Uptrace refuses to start when redis_cache.addrs is empty. If Redis becomes unavailable later, Uptrace keeps serving reads without the cache, so uptrace doctor reports a Redis failure only as a warning, but sign-ins and background jobs fail until Redis is back.

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:
  # Redis Ring server addresses
  addrs:
    alpha: redis-1:6379
    bravo: redis-2: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

On install, the package writes a random service.secret into /etc/uptrace/config.yml, which ships with the FIXME placeholder. It also sets the owner of the file to root:uptrace and its mode to 0640, so that other local users cannot read the secret. The install script changes only a file that still holds the placeholder, so a later upgrade keeps your secret, owner, and mode.

The package enables the uptrace service, but starts or restarts it only when the databases hold every migration of the installed release. On a first install, edit the config, run the database setup, and then start the service:

sudo systemctl start uptrace

uptrace serve refuses to start on databases that uptrace migrate up did not migrate, and names that command.

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 amd64 with the desired architecture:

wget https://github.com/uptrace/uptrace/releases/download/v2.0.3/uptrace_2.0.3_amd64.deb
sudo dpkg -i uptrace_2.0.3_amd64.deb

The written secret makes /etc/uptrace/config.yml a changed conffile. When an upgrade ships a new default config, dpkg asks what to do with the file. Keep your version, which is the default answer. If you install the package version instead, you lose your edits, and the package writes a new random secret.

RPM

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

wget https://github.com/uptrace/uptrace/releases/download/v2.0.3/uptrace-2.0.3-1.x86_64.rpm
sudo rpm -ivh uptrace-2.0.3-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 the Linux binary:

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

Create the Uptrace config:

./uptrace --config=/path/to/config.yml config create

The command writes a random service.secret into a new file that only its owner can read.

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.3/uptrace_darwin_amd64
chmod +x uptrace

Create the Uptrace config:

./uptrace --config=/path/to/config.yml config create

The command writes a random service.secret into a new file that only its owner can read.

Start Uptrace:

./uptrace --config=/path/to/config.yml serve

Windows

Download the Windows binary:

curl -L -o uptrace_windows_amd64.exe https://github.com/uptrace/uptrace/releases/download/v2.0.3/uptrace_windows_amd64.exe

Create the Uptrace config:

uptrace_windows_amd64.exe --config=/path/to/config.yml config create

The command writes a random service.secret into the new file. On Windows, the file takes the permissions of its folder, so put it in a folder that other users cannot read.

Start Uptrace:

uptrace_windows_amd64.exe --config=/path/to/config.yml serve

Other

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

Database Setup

After installing Uptrace and creating the databases, you need to initialize the database schemas and seed them with data from your config file.

Schema

Run the migrations to create the PostgreSQL and ClickHouse schemas:

uptrace --config=/etc/uptrace/config.yml migrate up

The same command creates the ClickHouse distributed tables and Kafka engine tables when your config enables them. To see what it will run first, add --plan. See upgrading Uptrace for the other migrate commands.

Seed Data

Seed the database with initial data from your config file, such as projects and users. Re-run this command whenever you change the seed data in your config:

uptrace --config=/etc/uptrace/config.yml db seed

Start Uptrace

With the DEB or RPM package, start the service:

sudo systemctl start uptrace

With a pre-compiled binary, run uptrace --config=/etc/uptrace/config.yml serve.

Check the installation

Check that Uptrace reaches every store and endpoint in your config:

uptrace --config=/etc/uptrace/config.yml doctor

The command reports each check as ok, warn, FAIL, or skip, and exits non-zero when a check fails. See checking the deployment for what each check proves.

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).

The config that the DEB and RPM packages and uptrace config create write listens for OTLP/HTTP on port 80 (together with the UI and the API) and for OTLP/gRPC on port 4317. To change the ports, edit listen.http.addr and listen.grpc.addr. Both ports are specified in the Uptrace DSN that you will receive after installing Uptrace.

Upgrading Uptrace

Check the supported upgrade paths first. If you run v2.0 or a v2.1 beta, also read upgrading from v2.0 or a v2.1 beta.

To upgrade Uptrace:

1. Back up your databases. Create backups of both PostgreSQL and ClickHouse before proceeding.
2. Install the new version using DEB, RPM, or a pre-compiled binary. The DEB and RPM packages do not restart Uptrace while migrations are unapplied.
3. Rewrite deprecated options, and check the config and the databases:
   shell

   uptrace config fix --write
   uptrace config validate
   uptrace preflight
   

4. Apply the migrations and restart Uptrace:
   shell

   uptrace migrate up --restart
   

   
   The command applies the schema changes in phases and restarts Uptrace at the right point, so Uptrace keeps accepting data during the upgrade.

See upgrading Uptrace to preview the migrations, recover from a failed step, and roll back.

What's Next?

Next, learn how to configure Uptrace for your needs.