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:

1. 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.
2. 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. Use http to disable TLS or https to enable TLS encryption
• localhost:14318 - The Uptrace backend address. Cloud deployments use api.uptrace.dev without specifying a port
• project1_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

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"),
    ),
)

# https://uptrace.dev/get/opentelemetry-python

import uptrace

# Copy your project DSN here or use UPTRACE_DSN env var
uptrace.configure_opentelemetry(
  dsn="<FIXME>",
  service_name="myservice",
  service_version="1.0.0",
  resource_attributes={"deployment.environment": "production"},
)

# https://uptrace.dev/get/opentelemetry-ruby

require 'uptrace'

# Copy your project DSN here or use UPTRACE_DSN env var
Uptrace.configure_opentelemetry(dsn: '<FIXME>') do |c|
  # c is OpenTelemetry::SDK::Configurator
  c.service_name = 'myservice'
  c.service_version = '1.0.0'

  c.resource = OpenTelemetry::SDK::Resources::Resource.create(
    'deployment.environment' => 'production'
  )
end

// https://uptrace.dev/get/opentelemetry-js/node

const uptrace = require('@uptrace/node')

uptrace
  .configureOpentelemetry({
    // Copy your project DSN here or use UPTRACE_DSN env var
    //dsn: '<FIXME>',
    serviceName: 'myservice',
    serviceVersion: '1.0.0',
    resourceAttributes: { 'deployment.environment': 'production' },
  })
  // Start OpenTelemetry SDK
  .start()
  // Execute main function when SDK is ready
  .then(main)

// https://uptrace.dev/get/opentelemetry-php

$uptrace = Uptrace\Distro::builder()
    // Copy your project DSN here or use UPTRACE_DSN env var
    //->setDsn('<FIXME>')
    ->setServiceName('myservice')
    ->setServiceVersion('1.0.0')
    ->setResourceAttributes(['deployment.environment' => 'production'])
    ->buildAndRegisterGlobal();

Troubleshooting Common Issues

No Data Appearing in Uptrace

If you're not seeing data in your Uptrace dashboard:

1. Verify DSN Configuration: Double-check that your DSN is correctly configured and accessible
2. Check Network Connectivity: Ensure your application can reach the Uptrace server (test with ping or telnet)
3. Validate SDK Initialization: Confirm that the OpenTelemetry SDK is properly initialized in your application
4. Review Application Logs: Look for OpenTelemetry export errors or warnings in your application logs
5. 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:

1. Adjust Sampling Rate: Reduce the sampling rate to decrease data volume
2. Optimize Export Settings: Fine-tune batch size and export frequency settings
3. Review Custom Instrumentation: Check for CPU-intensive custom spans or metrics collection
4. Monitor Resource Usage: Use system monitoring tools to identify bottlenecks

Slow Query Performance

If queries are running slowly in the Uptrace interface:

1. Optimize Query Structure: Modify your queries to improve performance
2. Use Appropriate Filters: Apply time range and service filters to limit data scope
3. Configure ClickHouse: Optimize your ClickHouse database configuration for better query performance
4. Index Management: Ensure proper indexing for frequently queried fields

Next Steps

Once you have Uptrace running and receiving data:

1. Explore the Dashboard: Familiarize yourself with the service overview and trace visualization
2. Set Up Alerts: Configure alerts for critical performance thresholds
3. Customize Views: Create custom dashboards for your specific monitoring needs
4. Integrate with CI/CD: Consider integrating performance monitoring into your deployment pipeline