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?
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.
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.
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 email@example.com:uptrace/uptrace.git cd example/rails
The app comes with some dependencies that you can install with:
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.
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
Just like with Rails, you need to install ActiveRecord instrumentation:
gem install opentelemetry-instrumentation-active_record
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
Next, you can learn about OpenTelemetry Ruby API to create your own instrumentations or browse existing Ruby instrumentations provided by the community.