OpenTelemetry: Ruby on Rails and ActiveRecord

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

---

• What is tracing?
• What is OpenTelemetry?
• Creating spans
• What is Uptrace?
• Example application
• Configuring OpenTelemetry
• Instrumenting Rails
• Instrumenting ActiveRecord
• What's next?

What is tracing?

OpenTelemetry tracing 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 spans. 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 OpenTelemetry.

What is OpenTelemetry?

OpenTelemetry is an open source and vendor-neutral API for OpenTelemetry tracing (including logs and errors) and OpenTelemetry metrics.

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 tools 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
  end
end

To record contextual information, you can annotate spans with attributes:

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

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

See OpenTelemetry Ruby tracing for details.

What is Uptrace?

Uptrace is a source-available APM 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 started 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 app that uses Rails and ActiveRecord with sqlite3 database. You can retrieve the source code with the following command:

git clone git@github.com:uptrace/uptrace.git
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.use_all

  c.service_name = 'myservice'
  c.service_version = '1.0.0'
end

See documentation for details.

Instrumenting Rails

To instrument Ruby on Rails app, you need a corresponding OpenTelemetry Rails instrumentation:

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'
end

Alternatively, you can call use_all 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:

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'
end

What's next?

Next, you can learn about OpenTelemetry Ruby API to create your own instrumentations or browse existing Ruby instrumentations provided by the community.