# Uptrace: an open source APM for OpenTelemetry traces, metrics and logs

> Uptrace stores OpenTelemetry data in ClickHouse and keeps metadata in PostgreSQL, with an AGPL-3.0 licence and a beta release line. It suits teams that already emit OTLP and want a self-hosted backend for all three signals.

**uptrace/uptrace** — Open source APM: OpenTelemetry traces, metrics, and logs

- Repository: https://github.com/uptrace/uptrace
- Website: https://uptrace.dev/get/hosted/open-source-apm
- Stars: 4,297 · Forks: 222
- Language: Go
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/uptrace-uptrace

## What Uptrace is for, and who ends up running it

Uptrace is an open source APM that accepts distributed traces, metrics and logs and presents them in a single UI. The README frames the goal as monitoring applications and troubleshooting issues, and lists the pieces a team normally assembles by hand: a query builder, dashboards, alerting rules, notifications, and integrations for most languages and frameworks. The audience is therefore not the developer who wants a hosted endpoint and nothing else. It is the team that already emits OpenTelemetry data, or is willing to, and would rather own the storage layer than pay per span. The repository ships example directories for Django, Express, Flask, gin-gorm, Rails, go-slog, go-zero, Sentry SDKs, Vector logs and the OpenTelemetry demo, which tells you the intended on-ramp is an existing application that already has instrumentation or can add it cheaply. The trade is explicit: you get control over retention and cost, and in exchange you operate ClickHouse and PostgreSQL yourself.

## How the ingestion path works: OTLP in, ClickHouse for data, PostgreSQL for metadata

The architecture splits storage by shape of data. ClickHouse holds the spans, metrics and logs; PostgreSQL holds metadata such as metric names and alerts. That separation matters when you plan capacity, because the two databases scale on different axes and fail differently. Ingestion is OpenTelemetry first. The README names OpenTelemetry as the collection framework and lists additional intake paths including Prometheus, Vector, FluentBit and CloudWatch. The bundled docker-compose.yml shows the shape of a local deployment: a clickhouse service with CLICKHOUSE_DB, CLICKHOUSE_USER and CLICKHOUSE_PASSWORD set to uptrace, a postgres service, an otelcol service from otel/opentelemetry-collector-contrib exposing 4317 and 4318, plus alertmanager and vector. The collector sits in front of the database, so your applications point at the collector rather than at Uptrace directly. The repository also carries a replace directive for github.com/grafana/tempo pointing at ./pkg/tempo, which lines up with the README claim that Grafana can use Uptrace as a Tempo or Prometheus datasource. Two performance figures appear in the README: more than 10K spans per second on a single core, and a 1KB span compressing to roughly 40 bytes. Both are the project's own claims, not measurements made here.

## Installing Uptrace locally with Docker and sending a first span

The README points at the cloud demo for a no-login look, and at the example/docker directory for running it locally. The compose file in that directory brings up the full stack. Start it from the repository root or from example/docker depending on where you cloned, then check that the collector is accepting traffic on the OTLP ports.

```yaml
services:
  clickhouse:
    image: clickhouse/clickhouse-server:25.3.3
    ports:
      - '8123:8123'
      - '9000:9000'
      - '9440:9440'

  otelcol:
    image: otel/opentelemetry-collector-contrib:0.88.0
    ports:
      - '4317:4317'
      - '4318:4318'
```

The services declared in docker-compose.yml are clickhouse, postgres, otelcol, alertmanager and vector. The collector listens on 4317 for gRPC and 4318 for HTTP, so an application exports OTLP to one of those ports. If you prefer not to run Docker, the Makefile builds a static binary with CGO disabled:

```bash
make uptrace
```

That target runs CGO_ENABLED=0 go build -trimpath -o ./bin/uptrace_$(GOOS)_$(GOARCH)$(EXTENSION) with the build info flags and ./cmd/uptrace as the package. It builds the server, not the databases, so you still need ClickHouse and PostgreSQL reachable. The Makefile also defines per-platform targets such as uptrace-linux_amd64 and uptrace-darwin_arm64, and a docker-uptrace target that builds for linux/arm64 and linux/amd64.

## The beta release line is the first thing to weigh

The most recent releases are v2.1.0-beta.8 on 2026-08-13, v2.1.0-beta.7 on 2026-06-05 and v2.1.0-beta.6 on 2026-05-25. There is no stable v2.1.0 tag in that list. A team that pins versions and upgrades on a schedule has to decide whether to run a beta in production, and the repository does not document a rollback procedure for a failed upgrade. The last push to the default branch was on 2026-08-13, so the project is being worked on, but activity is not the same as a stability guarantee. Treat the beta label as a real constraint rather than a formality: read the CHANGELOG.md before moving between beta versions, and test the upgrade against a copy of your ClickHouse data first. The second constraint is operational. Running Uptrace means running ClickHouse and PostgreSQL, and the compose file mounts a custom ClickHouse config at /etc/clickhouse-server/config.d/config.xml. Neither database is optional, and the README gives no single-binary embedded mode.

## Where Uptrace is the wrong tool

If your problem is error tracking rather than observability, Uptrace is a poor fit. The repository contains example/sentry-go, example/sentry-python and example/sentry-browser directories, which indicates Sentry SDK data can be ingested, but Uptrace is not an issue tracker with release health, assignment and regression detection as its centre of gravity. Teams that want that workflow should stay with a Sentry-style product. Uptrace is also the wrong choice when nobody wants to own a database. The README's cost argument rests on processing volume on your own hardware; if your team has no capacity to run ClickHouse, the operational bill replaces the vendor bill. A third case is a small service emitting a trickle of spans. The 10K spans per second figure describes headroom, not a requirement, and standing up two databases for a low-volume application is hard to justify against a hosted endpoint. Finally, if your organisation cannot accept AGPL-3.0, the licence decision comes before any technical evaluation.

## How Uptrace differs from Jaeger, Prometheus and Grafana

Jaeger is a tracing system. It stores and queries spans, and its data model is built around traces. Uptrace covers traces but also metrics and logs in one UI, and adds alerting rules with notifications through Email, Slack, WebHook and AlertManager. If you only need to find a slow span, Jaeger is a smaller thing to run. Prometheus is a metrics system with its own scrape model and PromQL. Uptrace accepts Prometheus data as an ingestion path and offers a PromQL-like language for aggregating metrics, but its storage is ClickHouse rather than Prometheus's local time series database, and it does not replace service discovery and scraping. Grafana is a visualisation layer, not a store. The README states that Grafana can be configured to use Uptrace as a Tempo or Prometheus datasource, so the two can sit in the same stack rather than compete. The practical difference across all three: Uptrace's bet is that one ClickHouse-backed store for all three signals, queried through one UI, costs less to run than three specialised systems at high span volume.

## Licence, upgrade cost and what to check before adopting

Uptrace is licensed under AGPL-3.0. That is a copyleft licence with a network clause, and it is the single item most likely to stop an adoption inside a company with strict licence review. This is not legal advice; the point is that the licence question should be settled before anyone spends a week on the compose file. On upgrade cost, the repository gives you a CHANGELOG.md, a Makefile with explicit build targets per platform, and a docker-uptrace target that builds for linux/arm64 and linux/amd64. Upgrading the server is therefore routine. Upgrading the storage is not: the compose file pins clickhouse/clickhouse-server:25.3.3 and postgres:15-alpine, and moving either major version is your migration to plan, not the project's. The README does not document a downgrade path. For a first evaluation, the cheapest concrete step is the one the README recommends: open the cloud demo, then run example/docker locally and confirm that your own collector configuration lands spans in the UI before you commit to a production deployment.

## Conclusion

Adopt Uptrace if you already emit OTLP and want traces, metrics and logs in one self-hosted UI backed by ClickHouse, and if AGPL-3.0 is acceptable for how you deploy it. Skip it if you need a stable tagged release rather than the current v2.1.0-beta line, or if you cannot operate ClickHouse and PostgreSQL. Before committing, verify that the beta release you pick handles your span volume, and confirm the licence position with your own legal review.

## FAQ

### Is Uptrace free?

The project is open source under AGPL-3.0, so the software itself carries no licence fee. The README also links a hosted offering at uptrace.dev, and running the open source version yourself means paying for the ClickHouse and PostgreSQL infrastructure it requires.

### How does Uptrace compare to Jaeger?

Jaeger is a tracing system built around spans and traces. Uptrace covers traces as well but adds metrics and logs in a single UI, plus alerting rules and notifications via Email, Slack, WebHook and AlertManager.

### How does Uptrace compare to Grafana?

Grafana is a visualisation layer rather than a datastore. According to the README, Grafana can be configured to use Uptrace as a Tempo or Prometheus datasource, so the two can run together instead of replacing each other.

### How does Uptrace compare to Prometheus?

Prometheus scrapes and stores metrics in its own time series database and is queried with PromQL. Uptrace accepts Prometheus data as an ingestion path and offers a PromQL-like language for metrics, but stores everything in ClickHouse alongside traces and logs.

### How does Uptrace compare to Sentry?

Sentry SDK data can be ingested, as the example/sentry-go, example/sentry-python and example/sentry-browser directories show, but Uptrace is an APM for traces, metrics and logs rather than an error-tracking product. The README does not describe an issue-tracking workflow.

### What are the alternatives to Uptrace?

The README positions Uptrace against the pieces teams usually assemble: Jaeger for traces, Prometheus for metrics, and Grafana as a visualisation layer that can query Uptrace as a Tempo or Prometheus datasource. It does not name a single product as a direct replacement.

## Sources

- [License: AGPL-3.0](https://github.com/uptrace/uptrace/blob/master/LICENSE)
- [Project website](https://uptrace.dev/get/hosted/open-source-apm)
- [README](https://github.com/uptrace/uptrace/blob/master/README.md)
- [Releases](https://github.com/uptrace/uptrace/releases)
- [uptrace/uptrace on GitHub](https://github.com/uptrace/uptrace)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/uptrace-uptrace