OpenTelemetry guide for Ruby on Rails

Distributed tracingopen in new window allows to precisely pinpoint the problem in complex systems, especially those built using a microservices architecture.

Tracing allow to follow requests as they travel through distributed systems. You get a full context of what is different, what is broken, and which logs & errors are relevant.

Using tracing, you can break down requests into . Span is an operation (unit of work) your app performs handling a request, for example, a database query or a network call.

Trace is a tree of spans that shows the path that a request makes through an app. Root span is the first span in a trace.

What is OpenTelemetry?

is an open source and vendor-neutral API for distributed tracingopen in new window (including logs and errors) and .

Otel specifies how to collect and export telemetry data in a vendor agnostic way. With OpenTelemetry, you can instrumentopen in new window your application once and then add or change vendors without changing the instrumentation, for example, many already support OpenTelemetry.

OpenTelemetry is available for most programming languages and provides interoperability across different languages and environments.

Creating spans

You can create a span using like this:

Uptraceopen in new window is an open source and blazingly fast powered by OpenTelemetry and ClickHouse. It allows you to identify and fix bugs in production faster knowing what conditions lead to which errors

You can install Uptraceopen in new window by downloading a DEB/RPM package or a pre-compiled binary.

Example application

In this tutorial, you will be instrumenting a toy appopen in new window that uses Django and PostgreSQL database client. You can retrieve the source code with the following command:

cd example/rails

bundle install

Configuring OpenTelemetry

Uptrace provides OpenTelemetry Rubyopen in new window distro that configures OpenTelemetry SDK for you. To install the distro:

Then you need to initialize OpenTelemetry whenever the app is started:

require 'uptrace'
# copy your project DSN here or use UPTRACE_DSN env var
Uptrace.configure_opentelemetry(dsn: '') do |c|
  c.service_name = 'myservice'
end

See for details.

To instrument Ruby on Rails app, you need a corresponding OpenTelemetry Rails instrumentationopen in new window:

gem install opentelemetry-instrumentation-rails

To instrument Rails app, call use with the name of the instrumentation:

Alternatively, you can call to install all available instrumentations:

require 'uptrace'
require 'opentelemetry-instrumentation-rails'
Uptrace.configure_opentelemetry(dsn: '') do |c|
  c.use_all
end

Instrumenting ActiveRecord

Just like with Rails, you need to install ActiveRecord instrumentation:

What’s next?

Next, you can learn about to create your own instrumentations or browse existing instrumentationsopen in new window provided by the community.