OpenTelemetry guide for Ruby on Rails

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 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 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 distributed tracingopen in new window (including logs and errors) and metricsopen in new window.

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

You can create a span using OpenTelemetry Ruby APIopen in new window like this:

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

What is Uptrace?

Uptraceopen in new window is an open source and blazingly fast distributed tracing toolopen 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 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:

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 Rubyopen in new window 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 documentationopen in new window 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'
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 APIopen in new window to create your own instrumentations or browse existing instrumentationsopen in new window provided by the community.