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:
- You can create a cloud account or host 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
. - 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. Usehttps
to enable TLS.localhost:14317
is an address of the Uptrace backend. The cloud version always uses theapi.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.
Attribute | Comment |
---|---|
service.name | Logical name of the service. Uptrace provides an overview of all services. |
service.version | The version string of the service API or implementation. |
deployment.environment | Name of the deployment environment (aka deployment tier). Uptrace can group spans from different environments separately. |
host.name | Name of the host. Usually, resource detectors discover and set this attribute automatically. |
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"),
),
)
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.