Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt

Use this file to discover all available pages before exploring further.

Use the OpenTelemetry Ruby SDK to instrument Ruby applications in a standard, vendor-agnostic, and future-proof way and send telemetry data to Honeycomb. In this guide, we will walk you through instrumenting with OpenTelemetry for Ruby, which will include adding both automatic and custom, or manual, instrumentation to your applications.

​
Before You Begin

Before you can set up automatic and custom instrumentation for your Ruby service, you will need to do a few things.

​
Prepare Your Development Environment

To complete the required steps, you will need:
  • A working Ruby environment with Ruby 2.5 or higher
  • A service written in Ruby

​
Get Your Honeycomb API Key

To send data to Honeycomb, you’ll need to sign up for a free Honeycomb account and create a Honeycomb Ingest API Key. To get started, you can create a key that you expect to swap out when you deploy to production. Name it something helpful, perhaps noting that it’s a getting started key. Make note of your API key; for security reasons, you will not be able to see the key again, and you will need it later!
For setup, make sure you check the “Can create datasets” checkbox so that your data will show up in Honeycomb. Later, when you replace this key with a permanent one, you can uncheck that box.
If you want to use an API key you previously stored in a secure location, you can also look up details for Honeycomb API Keys any time in your Environment Settings, and use them to retrieve keys from your storage location.

​
Add Automatic Instrumentation

To enable automatic instrumentation, you will add instrumentation packages to your application.

​
Acquire Dependencies

Add these gems to your Gemfile: 
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'
GemDescription
opentelemetry-sdkRequired to create spans
opentelemetry-exporter-otlpAn exporter to send data in the OTLP format
opentelemetry-instrumentation-allA meta package that provides instrumentation for Rails, Sinatra, several HTTP libraries, and more
Install the gems using your terminal: 
bundle install

​
Initialize

Initialize OpenTelemetry early in your application lifecycle. For Rails applications, we recommend that you use a Rails initializer. For other Ruby services, initialize as early as possible in the startup process. 
# 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

​
Configure the OpenTelemetry SDK

Use environment variables to configure OpenTelemetry to send events to Honeycomb: 
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io" # US instance
#export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.eu1.honeycomb.io" # EU instance
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key"
export OTEL_SERVICE_NAME="your-service-name"
VariableDescription
OTEL_EXPORTER_OTLP_ENDPOINTBase endpoint to which you want to send your telemetry data.
OTEL_EXPORTER_OTLP_HEADERSList of headers to apply to all outgoing telemetry data. Place your API Key generated in Honeycomb in the x-honeycomb-team header. Learn how to find your Honeycomb API Key.
OTEL_SERVICE_NAMEService name. When you send data, Honeycomb creates a dataset in which to store your data and uses this as the name. Can be any string.
If you are a Honeycomb Classic user, the Dataset also must be specified using the x-honeycomb-dataset header. A Dataset is a bucket where data gets stored in Honeycomb.
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key,x-honeycomb-dataset=your-dataset"

​
Run

Run your Ruby application. In Honeycomb’s UI, you should now see your application’s incoming requests and outgoing HTTP calls generate traces.

​
Add Custom Instrumentation

Automatic instrumentation is the easiest way to get started with instrumenting your code, but to get the most insight into your system, you should add custom, or 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 custom instrumentation, you need to add the OpenTelemetry SDK gem to your Gemfile: 
gem 'opentelemetry-sdk'

​
Acquire a Tracer

To create spans, you need to get a Tracer. 
require "opentelemetry/sdk"

tracer = OpenTelemetry.tracer_provider.tracer("tracer.name.here")
When you create a Tracer, OpenTelemetry requires you to give it a name as a string. This string is the only required parameter. When traces are sent to Honeycomb, the name of the Tracer is turned into the library.name field, which can be used to show all spans created from a particular tracer. In general, pick a name that matches the appropriate scope for your traces. If you have one tracer for each service, then use the service name. If you have multiple tracers that live in different “layers” of your application, then use the name that corresponds to that “layer”. The library.name field is also used with traces created from instrumentation libraries.

​
Add Attributes to Spans

It is often helpful 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 service in Honeycomb. 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.

​
Create New Spans

Automatic instrumentation can show the shape of requests to your system, but only you know the really important parts. To get the full picture of what is happening, you will have to add custom instrumentation and create some custom spans. To do this, grab the tracer from the OpenTelemetry API, and use it to create spans and add attributes. 
# 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

​
Add Multi-Span Attributes

Sometimes you want to add the same attribute to many spans within the same trace. This attribute may include variables calculated during your program, or other useful values for correlation or debugging purposes. To add this attribute to multiple spans, leverage the OpenTelemetry concept of baggage. Baggage allows you to add a key with a value as an attribute to every subsequent child span of the current application context, as long as you configured a BaggageSpanProcessor when you initialized OpenTelemetry.
  1. Install the baggage span processor gem using your terminal: 
    gem install opentelemetry-processor-baggage
  2. When configuring the OpenTelemetry SDK tracer provider, add the baggage span processor: 
    require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/processor/baggage'

OpenTelemetry::SDK.configure do |c|
  # Add the BaggageSpanProcessor to the collection of span processors
  c.add_span_processor(OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new)

  # Because the span processor list is no longer empty, the SDK will not use the
  # values in OTEL_TRACES_EXPORTER to instantiate exporters.
  # You'll need to declare your own values here in the configure block.
  #
  # These lines setup the default: a batching OTLP exporter.
  c.add_span_processor(
    # these constructors without arguments will pull config from the environment
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new()
    )
  )
end
  3. Add a baggage entry for the current trace and replace key and value with your desired key-value pair: 
    require 'opentelemetry/sdk'

context_with_baggage = OpenTelemetry::Baggage.set_value('key', 'value')
tracer.in_span('test-span', with_parent: context_with_baggage) do |span|
  # ... cool stuff
end
    Any Baggage attributes that you set in your application will be attached to outgoing network requests as a header. If your service communicates to a third party API, do NOT put sensitive information in the Baggage attributes.

​
Sampling

You can configure the OpenTelemetry SDK to sample the data it generates. Honeycomb weights sampled data based on sample rate, so you must set a resource attribute containing the sample rate. Use a TraceIdRatioBased sampler, with a ratio expressed as 1/N. Then, also create a resource attribute called SampleRate with the value of N. This allows Honeycomb to reweigh scalar values, like counts, so that they are accurate even with sampled data. In the example below, 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). 
export OTEL_TRACES_SAMPLER="traceidratio"
export OTEL_TRACES_SAMPLER_ARG=0.5
export OTEL_RESOURCE_ATTRIBUTES="SampleRate=2"
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.

​
Choosing between gRPC and HTTP

Most OpenTelemetry SDKs have an option to export telemetry as OTLP either over gRPC or HTTP/protobuf, with some also offering HTTP/JSON. If you are trying to choose between gRPC and HTTP, keep in mind:
  • Some SDKs default to using gRPC, and it may be easiest to start with the default option.
  • Some firewall policies are not set up to handle gRPC and require using HTTP.
  • gRPC may improve performance, but its long-lived connections may cause problems with load balancing, especially when using Refinery.
gRPC default export uses port 4317, whereas HTTP default export uses port 4318.

​
Endpoint URLs for OTLP/HTTP

When using the OTEL_EXPORTER_OTLP_ENDPOINT environment variable with an SDK and an HTTP exporter, the final path of the endpoint is modified by the SDK to represent the specific signal being sent. For example, when exporting trace data, the endpoint is updated to append v1/traces. When exporting metrics data, the endpoint is updated to append v1/metrics. So, if you were to set the OTEL_EXPORTER_OTLP_ENDPOINT to https://api.honeycomb.io, traces would be sent to https://api.honeycomb.io/v1/traces and metrics would be sent to https://api.honeycomb.io/v1/metrics. The same modification is not necessary for gRPC. 
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io # US instance
#export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.eu1.honeycomb.io # EU instance
If the desired outcome is to send data to a different endpoint depending on the signal, use OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT instead of the more generic OTEL_EXPORTER_OTLP_ENDPOINT. When using a signal-specific environment variable, these paths must be appended manually. Set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT for traces, appending the endpoint with v1/traces, and OTEL_EXPORTER_OTLP_METRICS_ENDPOINT for metrics, appending the endpoint with v1/metrics. Send both traces and metrics to Honeycomb using this method by setting the following variables: 
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.honeycomb.io/v1/traces # US instance
#export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.eu1.honeycomb.io/v1/traces # EU instance

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.honeycomb.io/v1/metrics # US instance
#export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.eu1.honeycomb.io/v1/metrics # EU instance
More details about endpoints and signals can be found in the OpenTelemetry Specification.

​
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 environment.

​
Troubleshooting

To explore common issues when sending data, visit Common Issues with Sending Data in Honeycomb.