Getting started with Uptrace
Uptrace is an open-source APM (Application Performance Monitoring) and observability platform that collects telemetry data including distributed traces, logs, and metrics using OpenTelemetry. It provides powerful visualization and analysis tools to help you monitor and debug your applications.
Quick Start
Getting started with Uptrace and OpenTelemetry is straightforward:
- Set up Uptrace: You can either create a cloud account or install Uptrace on your own servers. Both options will provide you with a DSN (Data Source Name) containing Uptrace connection details, such as
https://secret@api.uptrace.dev?grpc=4317
. - Configure OpenTelemetry: Use the DSN to configure OpenTelemetry for your programming language and start receiving telemetry data.
Need help? Join our community on Telegram, Slack, or start a discussion on GitHub.
DSN
The Uptrace DSN is a connection string that contains all the details needed to connect and send data to an Uptrace backend. It includes the backend address (host:port) and a secret token that provides write-only access to your project.
DSN Example
For the DSN http://project1_secret@localhost:14318?grpc=14317
, here's what each component means:
http
- Specifies the protocol. Usehttp
to disable TLS orhttps
to enable TLS encryptionlocalhost:14318
- The Uptrace backend address. Cloud deployments useapi.uptrace.dev
without specifying a portproject1_secret
- Your unique secret token used for authentication?grpc=14317
- The gRPC port for the OpenTelemetry protocol
Finding Your DSN
Uptrace automatically generates a unique DSN for each project. You can find your project's DSN on the Project Settings page within the Uptrace dashboard.
Monitoring Capabilities
Infrastructure Monitoring
Monitor host metrics, databases, and infrastructure components using:
- OpenTelemetry Collector - For comprehensive infrastructure monitoring
- Prometheus - For metrics collection and monitoring
- Supported services: Redis, PostgreSQL, MySQL, and many more
AWS Integration: If you're using AWS, you can send CloudWatch Metrics directly to Uptrace.
Log Monitoring
Centralize and analyze your application logs using:
- Vector - High-performance log collection and processing
- FluentBit - Lightweight log processor and forwarder
Combine logs with distributed traces for enhanced context and faster debugging capabilities.
AWS Integration: Send CloudWatch Logs directly to Uptrace for seamless AWS log monitoring.
Configuring Resource Attributes
Resource attributes are key-value pairs that provide essential metadata about your monitored services, processes, or containers. They help identify resources and enable effective filtering and grouping of telemetry data.
Essential Attributes
Attribute | Description |
---|---|
service.name | Logical name of the service. Uptrace uses this to provide service overviews and grouping. |
service.version | Version string of the service API or implementation for deployment tracking. |
deployment.environment | Deployment environment name (e.g., production, staging, development). Enables environment-based span grouping. |
host.name | Name of the host machine. Typically auto-discovered by OpenTelemetry resource detectors. |
Configuration Methods
Method 1: Environment Variables
Set attributes using the OTEL_RESOURCE_ATTRIBUTES
environment variable:
export OTEL_RESOURCE_ATTRIBUTES=service.name=myservice,service.version=1.0.0,deployment.environment=production
Method 2: SDK Configuration
Configure attributes during OpenTelemetry initialization in your application code:
// https://uptrace.dev/get/opentelemetry-go
import (
"github.com/uptrace/uptrace-go/uptrace"
"go.opentelemetry.io/otel/attribute"
)
uptrace.ConfigureOpentelemetry(
// Copy your project DSN here or use UPTRACE_DSN env var
//uptrace.WithDSN("<FIXME>"),
uptrace.WithServiceName("myservice"),
uptrace.WithServiceVersion("v1.0.0"),
uptrace.WithResourceAttributes(
attribute.String("deployment.environment", "production"),
),
)
Troubleshooting Common Issues
No Data Appearing in Uptrace
If you're not seeing data in your Uptrace dashboard:
- Verify DSN Configuration: Double-check that your DSN is correctly configured and accessible
- Check Network Connectivity: Ensure your application can reach the Uptrace server (test with ping or telnet)
- Validate SDK Initialization: Confirm that the OpenTelemetry SDK is properly initialized in your application
- Review Application Logs: Look for OpenTelemetry export errors or warnings in your application logs
- Test with Simple Examples: Try running basic OpenTelemetry examples to isolate configuration issues
Performance Issues (High CPU or Memory Usage)
If Uptrace is consuming excessive resources:
- Adjust Sampling Rate: Reduce the sampling rate to decrease data volume
- Optimize Export Settings: Fine-tune batch size and export frequency settings
- Review Custom Instrumentation: Check for CPU-intensive custom spans or metrics collection
- Monitor Resource Usage: Use system monitoring tools to identify bottlenecks
Slow Query Performance
If queries are running slowly in the Uptrace interface:
- Optimize Query Structure: Modify your queries to improve performance
- Use Appropriate Filters: Apply time range and service filters to limit data scope
- Configure ClickHouse: Optimize your ClickHouse database configuration for better query performance
- Index Management: Ensure proper indexing for frequently queried fields
Next Steps
Once you have Uptrace running and receiving data:
- Explore the Dashboard: Familiarize yourself with the service overview and trace visualization
- Set Up Alerts: Configure alerts for critical performance thresholds
- Customize Views: Create custom dashboards for your specific monitoring needs
- Integrate with CI/CD: Consider integrating performance monitoring into your deployment pipeline
Table of Contents