OpenTelemetry guide for Ruby on Rails and ActiveRecord

In this article, you will learn how to use OpenTelemetry with Uptrace to monitor Ruby on Rails performance.


What is tracing?

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

Tracing allows 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 spansopen in new window. 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.

To learn more about tracing, see Distributed Tracing using OpenTelemetryopen in new window.

What is OpenTelemetry?

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

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

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

Creating spans

To measure performance of database queries or HTTP requests, you can create a span using OpenTelemetry Ruby API:

require 'opentelemetry'

tracer = OpenTelemetry.tracer_provider.tracer('my_app_or_gem', '1.0.0')

def some_func()
  tracer.in_span('some-func') do |span|
    # the code you are measuring

To record contextual information, you can annotate spans with attributesopen in new window:

def create_user(name, email)
  tracer.in_span('insert-user', kind: :server) do |span|
    if span.recording?
      span.set_attribute('', name)
      span.set_attribute('', email)

    User.create(name: name, email: email)

See OpenTelemetry Ruby tracingopen in new window for details.

What is Uptrace?

Uptrace is a source-available APMopen in new window 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 get startedopen in new window with Uptrace by downloading a DEB/RPM package or a pre-compiled Go binary.

Example application

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

git clone
cd example/rails

The app comes with some dependencies that you can install with:

bundle install

Configuring OpenTelemetry

Uptrace provides OpenTelemetry Ruby distro that configures OpenTelemetry SDK for you. To install the distro:

gem install uptrace

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'
  c.service_version = '1.0.0'

See documentation for details.

Instrumenting Rails

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:

require 'uptrace'
require 'opentelemetry-instrumentation-rails'

Uptrace.configure_opentelemetry(dsn: '') do |c|
  c.use 'OpenTelemetry::Instrumentation::Rails'

Alternatively, you can call use_all to install all available instrumentations:

require 'uptrace'
require 'opentelemetry-instrumentation-rails'

Uptrace.configure_opentelemetry(dsn: '') do |c|

Instrumenting ActiveRecord

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

gem install opentelemetry-instrumentation-active_record

And call use with the name of the instrumentation:

require 'uptrace'
require 'opentelemetry-instrumentation-active_record'

Uptrace.configure_opentelemetry(dsn: '') do |c|
  c.use 'OpenTelemetry::Instrumentation::ActiveRecord'

What's next?

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

Last Updated: