Getting started with Uptrace

Get started

Uptrace collects telemetry data (traces, logs, metrics) using OpenTelemetry and provides powerful visualization and analysis tools.

Getting started with Uptrace and OpenTelemetry is easy:

1. You can create a cloud account or install Uptrace on your servers. Either way, you will obtain a DSN which contains Uptrace connection details, for example, https://secret@api.uptrace.dev?grpc=4317.
2. To start receiving telemetry data, use the DSN to configure OpenTelemetry for your programming language.

Have questions? Get help via Telegram, Slack, or start a discussion on GitHub.

DSN

Uptrace DSN (Data Source Name) is a connection string with details on how to connect and send data to an Uptrace backend. It contains a backend address (host:port) and a secret token that grants write-only access to the project.

For example, the DSN http://project1_secret_token@localhost:14318?grpc=14317 contains the following information:

• http tells the client to disable TLS. Use https to enable TLS.
• localhost:14317 is an address of the Uptrace backend. The cloud version always uses the api.uptrace.dev address without a port.
• project1_secret_token is a secret token that is used for authentication.
• ?grpc=14318 is a GRPC port for OpenTelemetry protocol.

Uptrace automatically generates a DSN for each project. You can find your project DSN on the Project Settings page:

Infrastructure monitoring

To monitor host (infrastructure) metrics, Redis, PostgreSQL, MySQL and many more, you can use OpenTelemetry Collector or Prometheus.

If you are using AWS, you can send CloudWatch Metrics directly to Uptrace.

Logs monitoring

To monitor logs, you can use Vector and FluentBit integrations. Combine logs with traces for better context and faster debugging.

If you are using AWS, you can send CloudWatch Logs directly to Uptrace.

Resource attributes

Resource attributes are key-value pairs that provide metadata about the monitored entity, such as a service, process, or container. They help identify the resource and provide additional information that can be used to filter and group telemetry data.

You can set those attributes by using the env resource detector and providing the OTEL_RESOURCE_ATTRIBUTES environment variable:

export OTEL_RESOURCE_ATTRIBUTES=service.name=myservice,service.version=1.0.0,deployment.environment=production

Or you can configure them during OpenTelemetry initialization:

// 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()
  // Then execute the 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

No data appearing in Uptrace

• Verify the DSN is correctly configured.
• Check network connectivity between your application and Uptrace server.
• Ensure OpenTelemetry SDK is properly initialized.
• Review application logs for export errors.

High CPU or memory usage

• Adjust sampling rate to reduce data volume.
• Optimize batch size and export frequency.
• Check for CPU-intensive custom spans or metrics.

Slow queries in UI

• Change the query to make it faster.
• Optimize your ClickHouse configuration.