OpenTelemetry for Ruby | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

OpenTelemetry for Ruby

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.

Requirements  🔗

These instructions will explain how to set up automatic and manual instrumentation for a Ruby service. In order to follow along, you will need:

  • Ruby 2.5 or higher
  • A service written in Ruby
  • A Honeycomb API Key. You can find your API key on your Team Settings page. If you don’t have an API key yet, sign up for a free Honeycomb account.

Automatic Instrumentation  🔗

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.

Initialization  🔗

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.

OpenTelemetry initialization:

# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
  c.use_all() # enables all instrumentation!
end

Environment configuration:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key,x-honeycomb-dataset=your-dataset"
export OTEL_SERVICE_NAME="your-service-name"

A complete example can be viewed here.

Adding Manual Instrumentation  🔗

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:

gem 'opentelemetry-sdk'

Adding Attributes to Spans  🔗

It’s often beneficial to add information 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 WHERE, GROUP BY, or ORDER clauses in the Honeycomb query builder.

Creating New Spans  🔗

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

Sampling  🔗

export OTEL_TRACES_SAMPLER="traceidratio"
export OTEL_TRACES_SAMPLER_ARG=0.5
export OTEL_RESOURCE_ATTRIBUTES="SampleRate=2"

You can configure the OpenTelemetry SDK to sample the data it generates. Honeycomb re-weights sampled data, so it is recommended that you set a resource attribute containing the sample rate.

In the example above, our goal is to keep approximately half (1/2) of the data volume. The resource attribute contains the denominator (2), while the OpenTelemetry sampler argument contains the decimal value (0.5).

If you have multiple services that communicate with each other, it is important that they have the same sampling configuration. Otherwise, each service might make a different sampling decision, resulting in incomplete or broken traces. You can sample using a standalone proxy as an alternative, like Honeycomb Refinery, or when you have more robust sampling needs.

Distributed Trace Propagation  🔗

When a service calls another service, you want to ensure that the relevant trace information is propagated from one service to the other. This allows Honeycomb to connect the two services in a trace.

Distributed tracing enables you to trace and visualize interactions between multiple instrumented services. For example, your users may interact with a front-end API service, which talks to two internal APIs to fulfill their request. In order to have traces connect spans for all these services, it is necessary to propagate trace context between these services, usually by using an HTTP header.

Both the sending and receiving service must use the same propagation format, and both services must be configured to send data to the same Honeycomb dataset.

Troubleshooting  🔗

If no errors appear in the console but your data is not in Honeycomb as expected, use a ConsoleSpanExporter to print your spans to the console. This will help confirm whether your app is being instrumented with the data you expect.

As shown in the OpenTelemetry SDK for Ruby, configuration options can be set via environment variables or programmatically.

To use an environment variable to print to the console, set the variable before calling configure:

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'

ENV['OTEL_TRACES_EXPORTER'] = 'console' # for debugging
OpenTelemetry::SDK.configure do |c|
  c.use_all()
end

Alternatively, add the ConsoleSpanExporter to your configuration:

 OpenTelemetry::SDK.configure do |c|
   c.add_span_processor(
     OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
       OpenTelemetry::SDK::Trace::Export::ConsoleSpanExporter.new
     )
   )
...
end

Keep in mind that printing to the console is not recommended for production and should only be used for debugging purposes.