Skip to content
Back to Stack Recommender

Uptrace

Uptrace — open-source APM with OpenTelemetry tracing and ClickHouse.

MonitoringModerate

Stack Components

PlatformUptrace
StorageClickHouse

Why

Unified traces + metrics, query traces with SQL, cost-effective self-hosting. OpenTelemetry became the CNCF instrumentation standard in 2024, used by 70%+ of cloud-native orgs.

Sentry and Datadog lead error tracking with 30k+ paying customers each.

When

Use for OTel-based self-hosted APM. Avoid for cloud-managed preference.

How

1. Deploy Uptrace via Docker 2. Configure OTel to export to Uptrace 3. View traces in UI 4. Set up alerts

Example

const exporter = new OTLPSpanExporter({ url: 'http://localhost:14318' }); // Uptrace — usage example import { Uptrace } from "mon2-uptrace"; const result = await uptrace({ input: "data" }); console.log(result);

Common Problems

  • ⚠ClickHouse schema migration — follow upgrade guide
  • ⚠High card span names — use sampling
  • ⚠Configuration drift between environments — use infrastructure-as-code (Terraform/Pulumi) to keep dev/staging/prod identical

Best Practices

  • ✓Use Uptrace query language for custom analysis
  • ✓Monitor ClickHouse disk usage
  • ✓Set up health checks and graceful shutdown — handle SIGTERM to drain in-flight requests before exit

FAQ

What is Uptrace and what projects is it for?

Uptrace — open-source APM with OpenTelemetry tracing and ClickHouse. It pairs layered technologies for end-to-end type safety and out-of-the-box deploys, fitting everything from MVPs to production SaaS.

How do I spin up a working demo with Uptrace in 10 minutes?

Two steps: (1) Deploy Uptrace via Docker; (2) Configure OTel to export to Uptrace. Get the local dev server running, then wire one real data source to verify the end-to-end loop.

What is the most common pitfall with Uptrace and how do I avoid it?

The most common pitfall is: ClickHouse schema migration — follow upgrade guide. Avoid it by adding the matching checklist to your PR template and running type-check + lint + unit tests in CI — three gates before merge.

What are the best practices for Uptrace?

Best practices for Uptrace include: Use Uptrace query language for custom analysis; Monitor ClickHouse disk usage; Set up health checks and graceful shutdown — handle SIGTERM to drain in-flight requests before exit. The first one — "Use Uptrace query language for custom analysis" — should be set up at project init to avoid costly rework later.

When should I NOT choose Uptrace?

Pick something else in three cases: (1) the team has zero experience with the core framework and the deadline is tight (learning-curve risk); (2) it's a pure content/marketing site (Astro is lighter); (3) you need very high throughput (>10k RPS) or strict-consistency microservices (Go/Rust). Uptrace shines for mid-to-high complexity full-stack and API work — don't over-engineer simple static pages with it.