OpenTelemetry for Ruby can be used to add automatic and manual instrumentation to your applications and have trace data sent to Honeycomb. Automatic instrumentation is enabled by adding instrumentation packages. Manual instrumentation can be added using the OpenTelemetry API.
These instructions will explain how to set up automatic and manual instrumentation for a Ruby service. In order to follow along, you will need:
To auto-instrument your Ruby application, add these gems to your Gemfile:
gem 'opentelemetry-sdk' gem 'opentelemetry-exporter-otlp' gem 'opentelemetry-instrumentation-all'
The inclusion of
opentelemetry-instrumentation-all in the above list provides instrumentations for Rails, Sinatra, several HTTP libraries, and more.
The OpenTelemetry initialization needs to happen early in your application lifecycle. For Rails applications, the usual way to initialize OpenTelemetry is in a Rails initializer. For other Ruby services, perform this initialization as early as possible in the start-up process.
# config/initializers/opentelemetry.rb require 'opentelemetry/sdk' require 'opentelemetry/exporter/otlp' require 'opentelemetry/instrumentation/all' OpenTelemetry::SDK.configure do |c| c.service_name = '<YOUR_SERVICE_NAME>' c.use_all() # enables all instrumentation! end
A complete example can be viewed here.
Auto-instrumentation is the easiest way to get started with instrumenting your code, but in order to get the most insight into your system, you should add manual instrumentation where appropriate. To do this, use the OpenTelemetry SDK to access the currently executing span and add attributes to it, and/or to create new spans.
To add manual instrumentation, you need to add the OpenTelemetry SDK gem to your Gemfile:
It’s often beneficial to add context to a currently executing span in a trace. For example, you may have an application or service that handles users, and you want to associate the user with the span when querying your dataset in Honeycomb. In order to do this, get the current span from the context and set an attribute with the user ID:
# somewhere within the service, the SDK has been required and configured require 'opentelemetry/sdk' OpenTelemetry::SDK.configure do ... end # ... def handle_user(user) current_span = OpenTelemetry::Trace.current_span current_span.set_attribute("user_id", user.id) end
This will add a
user_id field to the current span so that you can use the field in
GROUP BY, or
ORDER clauses in the Honeycomb query builder.
Auto-instrumentation can show the shape of requests to your system, but only you know the really important parts. In order to get the full picture of what’s happening, you will have to add manual instrumentation and create some custom spans. To do this, grab the tracer from the OpenTelemetry API:
# somewhere within the service, the SDK has been required and configured require 'opentelemetry/sdk' OpenTelemetry::SDK.configure do ... end # ... def run_query tracer = OpenTelemetry.tracer_provider.tracer('my-tracer') tracer.in_span("expensive-query") do |span| # ... cool stuff span.set_attribute('coolness', 100) end end