# Introduction to Uptrace

# What is Uptrace?

Uptraceopen in new window is a tracing system that monitors performance, errors, and logs. It collects traces, aggregates and processes them to help you pinpoint failures and find performance bottlenecks.

Getting started is easy:

  1. See Uptrace in action: playgroundopen in new window.
  2. Follow getting started guide for your programming language.
  3. Learn about distributed tracing.
  4. Instrumentopen in new window your application with plugins for popular frameworks and libraries.

# Basic terms

To get started with tracing, you need to understand the following terms:

  • Span is an operation (unit of work) in a trace. For example, an HTTP endpoint or a database query.
  • Trace is a tree of spans that shows the path that a request makes through an app.
  • You create spans with a tracer. Usually, there is a single tracer for an app or a library.
  • Attribute is a key-value pair on a span that carries some information about the span operation. For example, host.name: 'localhost'.
  • Event is an entity within a span. Think of it as a span that does not have end time (and thus duration). Events can have attributes too.
  • OpenTelemetryopen in new window is a vendor-neutral API for distributed traces and metrics. Uptrace uses OpenTelemetry to collect telemetry data.
  • Uptrace client is an OpenTelemery distribution configured to export data to Uptrace.

# Sign up for a free account

If you don’t already have an account, you can sign up for a free tier account hereopen in new window.

# Sending data to Uptrace

Uptrace uses OpenTelemetryopen in new window to collect traces, logs, errors, and metrics from your application. To collect that data, you need to annotate (instrument) important operations with spans and metrics.

First, you need to install and configure Uptrace client using your project DSN (connection string), for example, https://<token>@api.uptrace.dev/<project_id>.

Then you need to instrument your services using OpenTelemetry instrumentationsopen in new window. Instrumentations are plugins for popular frameworks and libraries which capture telemetry data and allow you to see how requests progress through different services and components.

Lastly, you can create your own instrumentations using OpenTelemetry API. Use attributes to record contextual information and events to monitor errors and logs.

# What to instrument

You don't need to instrument all functions to get the most out of Uptrace. It can take a lot of time and usually is not needed. Consider prioritizing the following operations:

  • Network operations, for example, HTTP requests or RPC calls.
  • Filesystem operations, for example, reading/writing to a file.
  • Database queries, which combine network and filesystem operations. Besides, being able to see executed queries is invaluable. Uptrace will also pretty-print them for you.
  • Known or potential performance bottlenecks.

# Have questions?

Don't hesitate to email us. We use your questions to improve the docs and reply as soon as possible.