Getting started with Uptrace

Uptrace is an open-source observability and APM platform that ingests distributed traces, metrics, and logs via OpenTelemetry. This page explains how to provision an Uptrace project, find your DSN, and begin streaming telemetry from your services.

Quick start

1. Provision Uptrace. Either sign up for Uptrace Cloud or self-host Uptrace. Both deployment options expose a project DSN such as https://secret@api.uptrace.dev?grpc=4317.
2. Configure OpenTelemetry. Paste the DSN into the OpenTelemetry SDK for your language (see the distributions below) and start the application. Uptrace immediately begins receiving spans, metrics, and logs.

Questions? Reach the team on Telegram, Slack, or GitHub Discussions.

DSN

Every project has a DSN (Data Source Name) that packages the Uptrace endpoint and credentials into one connection string. You can reveal the DSN under Project Settings → Connection details.

Anatomy of a DSN

Example: http://project1_secret@localhost:14318?grpc=14317

• http — Transport protocol. Use https when TLS is enabled.
• localhost:14318 — Uptrace HTTP endpoint. Cloud projects use api.uptrace.dev.
• project1_secret — Write-only token that authenticates the project.
• ?grpc=14317 — Optional gRPC endpoint for native OpenTelemetry exporters.

Share the DSN only with collectors or services that must send data; it is not required to view your dashboards.

Ports

Uptrace accepts data via OTLP/gRPC and OTLP/HTTP on separate ports:

Most OpenTelemetry SDKs default to gRPC. Use HTTP when gRPC is blocked by firewalls or proxies.

Self-hosted ports are configured in uptrace.yml via listen.grpc.addr and listen.http.addr. You can also use site.url and site.ingest_url to customize DSN host.

Monitoring capabilities

Infrastructure

• OpenTelemetry Collector gathers host metrics, databases, and middleware signals before forwarding them to Uptrace.
• Prometheus scrapes metrics and exports them directly to Uptrace.
• AWS users can stream CloudWatch Metrics for EC2, RDS, and other managed services.

Kubernetes

Deploy the OpenTelemetry Collector as a DaemonSet or use the Operator to scrape kubelet, API server, and pod-level metrics. Enrich traces with k8s.* attributes, then forward the data via your DSN. Follow the Kubernetes monitoring guide for Helm steps, RBAC rules, and sampling advice.

Logs

• Vector provides high-throughput log shipping with filtering and enrichment.
• Fluent Bit offers a lightweight forwarder for containers and edge nodes.
• AWS environments can ingest CloudWatch Logs for centralized searching alongside traces.

Correlate logs with spans to jump directly from an error message to the distributed trace that produced it.

Troubleshooting

Data is missing

1. Confirm the DSN matches the project and environment you are instrumenting.
2. Validate network routes between your service and the Uptrace endpoint (try curl against the DSN host).
3. Ensure the OpenTelemetry SDK initializes before your application starts handling requests.
4. Inspect application logs for exporter failures or authentication errors.
5. Run a minimal sample app to isolate whether the issue is in instrumentation or platform networking.

High resource usage

1. Lower the sampling rate to reduce span volume.
2. Tune exporter batch sizes, timeouts, and concurrency.
3. Audit custom instrumentation for expensive synchronous work.
4. Use system monitors to confirm whether pressure comes from CPU, memory, or I/O.

Slow queries in the UI

1. Simplify filters or reshape the query to scan less data.
2. Limit the time range or select a specific service/environment tag.
3. Verify ClickHouse configuration and retention policies for the dataset backing your project.
4. Rebuild indexes for frequently queried columns if you self-host ClickHouse.

Next steps

1. Explore dashboards, service maps, error reports, and span tables.
2. Define alerts for latency, error rate, or infrastructure saturation.
3. Customize dashboards for specific teams or services.
4. Integrate Uptrace checks into CI/CD so every release is covered by tracing and metrics.