The Ruby Beeline for Honeycomb is quick and easy way to instrument your Ruby application. It includes several optional wrappers that automatically instrument HTTP requests and database queries.
It provides automatic tracing out of the box, linking database queries to the HTTP request from which they originated. While this is a great way to get general insights about your app as quickly as possible, as you forge ahead on your observability journey you may find you’d like to add new events or traces to add more details specific to your app. The Ruby Beeline provides simple interfaces for adding both.
To see an example of the Ruby Beeline in action, try out the examples.
If you’d like to see more options in the Ruby Beeline, please file an issue or vote up one already filed! You can also contact us at support@honeycomb.io.
You can find your API key on your Team Settings page. If you don’t have a Honeycomb account yet, sign up for free.
To install the Ruby Beeline for your application:
Add honeycomb-beeline to your Gemfile:
gem 'honeycomb-beeline'
If you have a Rails application, you can run the generator to create your configuration file:
bundle exec rails generate honeycomb YOUR_API_KEY --dataset your-dataset-name
Otherwise in your code, initialize the Beeline with your API key and dataset name:
Honeycomb.configure do |config|
# Get this via https://ui.honeycomb.io/account after signing up for Honeycomb
config.write_key = 'YOUR_API_KEY'
# The name of your app is a good choice to start with
config.dataset = 'my-ruby-app'
end
The Ruby Beeline tracks the current span within the overall trace. This allows you to add as many additional custom fields as you like.
Here is an example of adding a custom field to the current span:
def calculate_big_number
# ... do work, find a big number
Honeycomb.add_field('big_num', result)
# ... do thing with big_num, maybe something fails
Honeycomb.add_field('error', err)
end
Additional fields are added under the app. namespace. For example, the
field above would appear in your event as app.big_num.
The namespace groups your fields together to make them easy to find and examine.
If you prefer to avoid the app. namespace, for example in order to overwrite an automatically-populated field,
you can have your block take the current span as a paramter and call add_field directly on that instance.
def calculate_another_big_number
Honeycomb.start_span(name: 'big_number_calculation') do |span|
# ... do work, find another big_num
span.add_field('handler.name', 'calc_other_big_num')
end
end
These additional fields are your opportunity to add important and detailed context to your instrumentation. Put a timer around a section of code, add per- user information, include details about what it took to craft a response, and so on. It is expected that some fields will only be present on some requests. Error handlers are a great example of this; they will obviously only exist when an error has occurred.
It is common practice to add in these fields along the way as they are processed in different levels of middleware. For example, if you have an authentication middleware, it would add a field with the authenticated user’s ID and name as soon as it resolves them. Later on in the call stack, you might add additional fields describing what the user is trying to achieve with this specific HTTP request.
If you’re interested in adding custom fields to all spans, use add_field_to_trace instead.
add_field_to_trace adds the field to both the currently active span and all other
spans that have yet to be sent and are involved in this trace that occur within this process.
Additionally, these fields are packaged up and passed along to downstream processes
if they are also using a beeline.
This function is good for adding context that is better scoped to the request than
this specific unit of work, e.g. user IDs, globally relevant feature flags, errors, etc.
Fields added here are also prefixed with app.
We encourage people to think about instrumentation in terms of “units of work”. As your program grows, what constitutes a unit of work is likely to be portions of your overall service rather than an entire run. Spans are a way of breaking up a single external action (say, an HTTP request) into several smaller units in order to gain more insight into your service. Together, many spans make a trace, which you can visualize traces within the Honeycomb query builder.
Adding spans with the Ruby Beeline is easy! Here is an example, where calls to slow_operation get their own span within the trace:
def slow_operation
Honeycomb.start_span(name: 'slow_operation') do |span|
# ... go on and do the slow opp, add more data along the way
span.add_field('interesting_thing', 'banana')
end
end
Spans always get a few fields:
slow_operationYou are always welcome (and encouraged!) to add additional fields to spans using
the Honeycomb.add_field method.
The Ruby Beeline integrates with other common ruby gems in order to populate spans and traces with useful information.
The Ruby Beeline can listen to any ActiveSupport instrumentation calls in your application to produce spans from subscribed event types. This is the primary means by which the Rails framework is instrumented.
Add the identifier for the ActiveSupport notification to an array assigned to the Beeline configuration’s notification_events property.
The Beeline will generate a span for the notification event with the event’s keys added as fields.
Event keys whose values are complex objects will be coerced to strings with #to_s.
Honeycomb.configure do |config|
config.write_key = 'YOUR_API_KEY'
config.dataset = 'ruby'
config.notification_events = %w[
custom_events.are_cool
].freeze
end
To subscribe to a notification event type and customize the fields that will appear on its span, use the Beeline configuration’s #on_notification_event method.
Call #on_notification_event with a specific event name, provide a block that receives a name, span, and payload, then customize the span within the block.
For example, to add fields to the span for a perform.active_job notification event with values from the Job object on its job key:
Honeycomb.configure do |config|
config.write_key = "YOUR_API_KEY"
config.dataset = "ruby"
# subscribe to some interesting Rails notifications
config.notification_events = %w[
sql.active_record
render_template.action_view
render_partial.action_view
render_collection.action_view
perform.active_job
process_action.action_controller
send_file.action_controller
send_data.action_controller
deliver.action_mailer
].freeze
# customize the handling of a particular notification
# it's OK if the name also appears in the list given to #notifications_events!
config.on_notification_event("perform.active_job") do |name, span, payload|
span.add_field("#{name}.adapter", payload["adapter"].class)
job = payload["job"]
span.add_field("#{name}.job_class", job.class)
span.add_field("#{name}.provider_id", job.provider_job_id)
span.add_field("#{name}.scheduled_at", job.scheduled_at)
end
# on_notification_event can be called multiple times with different event names
# subscribe and customize the handling of some custom notification type of your own
config.on_notification_event("custom_events.are_cool") do |name, span, payload|
# let's reuse the behavior of the default handler
config.default_handler.call(name, span, payload)
# ... and then add to or change the data on the span for this event
span.add_field("#{name}.reason", "Because you can annotate their spans how you like.")
span.add_field("#{name}.coolness_factor", payload["level_of_cool"])
end
The ruby beeline will automatically instrument any calls made using v2 or v3 of the aws-sdk gem and create a span for each call.
The Ruby Beeline will attempt to propagate outgoing HTTP requests with a trace propagation header. This allows other services that are using a Beeline to produce a distributed trace.
The Ruby Beeline provides a piece of rack middleware that can be used in your rack applications. This will create a trace and root span for each request and continue any distributed traces with trace ids included from other Beelines in the header.
app = Rack::Builder.new do |builder|
builder.use Honeycomb::Rack::Middleware, client: Honeycomb.client
builder.run RackApp.new
end
The Ruby Beeline provides a Rails generator for easy configuration.
bundle exec rails generate honeycomb YOUR_API_KEY --dataset DATASET_NAME
With the provided API key and dataset name, the rails generate honeycomb command will generate a Rails initializer with some basic Active Support events selected and a sample presend_hook to demonstrate removing potentially sensitive information from notification events.
The Rails Guide for Active Support Instrumentation documents many more types of events to which you can subscribe to send to Honeycomb.
The handling of notification events can be customized based on the event identifier; see the Active Support section for details.
NOTE: The Beeline does not sanitize raw SQL.
Database queries from .find_by_sql() or ActiveRecord.connection.execute will be transmitted to Honeycomb in their entirety.
To prevent sending sensitive information to Honeycomb, use the ActiveRecord query interface and ensure prepared_statements is set to true in config/database.yml for your database adapter.
Most Rails database adapters default to using prepared statements, but some, like MySQL, do not.
Honeycomb.configure do |config|
config.write_key = 'YOUR_API_KEY'
config.dataset = "rails"
config.presend_hook do |fields|
if fields["name"] == "redis" && fields.has_key?("redis.command")
# remove potential PII from the redis command
if fields["redis.command"].respond_to? :split
fields["redis.command"] = fields["redis.command"].split.first
end
end
if fields["name"] == "sql.active_record"
# remove potential PII from the active record events
fields.delete("sql.active_record.binds")
fields.delete("sql.active_record.type_casted_binds")
end
end
config.notification_events = %w[
sql.active_record
render_template.action_view
render_partial.action_view
render_collection.action_view
process_action.action_controller
send_file.action_controller
send_data.action_controller
deliver.action_mailer
].freeze
end
The Ruby Beeline will automatically instrument your rake tasks and create a trace and root span for each rake task.
The Ruby Beeline will automatically instrument your sequel database calls and create a span for each call.
The Ruby Beeline enhances the provided rack middleware to collect extra information for sinatra application.
use Honeycomb::Sinatra::Middleware, client: Honeycomb.client
get '/' do
'Hello from Honeycomb'
end
The Beeline will use any https_proxy, http_proxy, and no_proxy environment variables set for the process for all event traffic to Honeycomb.
Note: To use the standard proxy environment variables, ensure that the underlying Ruby Libhoney client is version 1.18.0 or greater.
Proxy support was added in Libhoney version 1.14.0 and was configured via a proxy_config Array passed during client initialization.
Array-style proxy configuration will be deprecated in Libhoney 2.0.
Honeycomb.configure do |config|
config.client = Libhoney::Client.new(
writekey: 'YOUR_API_KEY',
dataset: 'ruby',
proxy_config: ['myproxy.example.com', 8080])
)
end
# ... or if you need to authenticate to your proxy
Honeycomb.configure do |config|
config.client = Libhoney::Client.new(
writekey: 'YOUR_API_KEY',
dataset: 'ruby',
proxy_config: ['myproxy.example.com', 8080, 'username', 'password'])
)
end
If you have some transformations you would like to make on every span before it
leaves the process for Honeycomb, the presend_hook is your opportunity to make
these changes. Examples are scrubbing sensitive data (eg you may want to ensure
specific fields are dropped or hashed) or augmenting data (eg making out-of-band
translations between an ID and a more human readable version). Similar to the
sample_hook discussed below, you pass the presend_hook a block that will
be called on every span with the fields of that span as an argument. The
function is free to mutate the hash passed in and those mutations will be what
finally gets sent to Honeycomb.
As an example, say we have some HTTP requests that provide sensitive values which have been added to a span. This code will examine all spans just before they’re sent to Honeycomb and replace the sensitive values with “[REDACTED]”.
Honeycomb.configure do |config|
config.presend_hook do |fields|
fields['credit_card_number'] = '[REDACTED]'
end
end
To sample a portion of events for very
high throughput services, include a custom client with a sample_rate in the initialization of the Ruby Beeline. This sends 1/n of all events, so a sample rate of 5 would send 20% of your events. Try starting with
a value of 10:
Honeycomb.configure do |config|
config.client = Libhoney::Client.new(
writekey: 'YOUR_API_KEY',
dataset: 'ruby',
sample_rate: 5
)
end
Sampling is performed by default on a per-trace level in the Ruby Beeline, so adding sampling won’t break your traces. Either all spans in a trace will be sent, or no spans in the trace will be sent.
The Honeycomb engine reweights query results to ensure that sampled computations return correct results.
Our Beeline lets you define a sample_hook in order to customize the logic used for deterministic per-trace sampling.
For example, assume you have instrumented an HTTP server. You’d like to keep all errored requests and heavily sample healthy traffic (200 response codes). Also, you don’t really care about 302 redirects in your app, so want to drop those. You could define a sampler function like so:
class CustomSampler
extend Honeycomb::DeterministicSampler
def self.sample(fields)
# capture everything by default
sample_rate = 1
case fields['app.response_code']
when 302
return [false, 0]
when 200
# only keep 1 out of every 100 traces for successful requests
sample_rate = 100
end
if should_sample(sample_rate, fields['trace.trace_id'])
return [true, sample_rate]
end
return [false, 0]
end
end
Honeycomb.configure do |config|
config.sample_hook do |fields|
CustomSampler.sample(fields)
end
end
Note: Defining a sampling hook overrides the deterministic sampling
behavior for trace IDs. Unless you take trace.trace_id into account (as we did
above by extending the DeterministicSampler), you will get incomplete traces.
If a single trace in your system can traverse multiple processes, you’ll need a way to connect the spans emitted by each service into a single trace. This is handled by propagating trace context via an HTTP header.
The Honeycomb beelines support trace headers in a Honeycomb specific format as well as the W3C Trace Context format.
If you are using the Honeycomb Beeline and faraday to make HTTP calls, you’re all set and trace propagation is automatically handled for you.
In order to support distributed traces that include services instrumented with a Honeycomb Beeline and OpenTelemetry, the Beeline includes marshal and unmarshal functions that can generate and parse W3C Trace Context headers, the format used by OpenTelemetry.
In order to specify that a service should parse W3C Trace Context headers from
incoming requests, you must specify an http_trace_parser_hook in the beeline configuration.
An http_trace_parser_hook is a function that takes a rack env as an argument and
returns a Honeycomb::Propagation::Context. The rack env is provided to the function
so that the author can make decisions about whether to trust the incoming headers based
on information contained in the request (e.g. perhaps you don’t want to accept headers
from the public internet).
require "honeycomb-beeline"
require "honeycomb/propagation/w3c"
Honeycomb.configure do |config|
...
config.http_trace_parser_hook do |env|
Honeycomb::W3CPropagation::UnmarshalTraceContext.parse_rack_env env
end
end
In order to send trace propagation headers in a supported format, you must specify an
http_trace_propagation_hook. This is done during the configuration of the beeline.
An http_trace_propagation_hook is a function that takes an Faraday env and a Honeycomb::Propagation::Context
as arguments and returns a hash of name, value pairs representing serialized headers. Similar to the parsing
hook described above, the Faraday env and Propagation Context objects are passed to this function so
that the author can make decisions about whether to include trace context in the outgoing request (e.g. you
may not wish to send trace context headers when calling a 3rd party API).
require "honeycomb-beeline"
require "honeycomb/propagation/w3c"
Honeycomb.configure do |config|
...
config.http_trace_propagation_hook do |env, context|
Honeycomb::W3CPropagation::MarshalTraceContext.parse_faraday_env env, context
end
end
Because we specified an http_trace_propagation_hook that returns a serialized header in W3C trace context format,
the outgoing request will include the appropriate trace context header.
There are three general approaches to finding out what’s wrong when the Ruby Beeline isn’t doing what you expect.
Add the debug line in the config block.
Honeycomb.configure do |config|
# any other configuration...
config.debug = true
end
By using a Libhoney LogClient when configuring the Ruby Beeline you can send the events to STDOUT.
Honeycomb.configure do |config|
config.client = Libhoney::LogClient.new
end
If you are having issues with a specific integration with Rails, Faraday, Sequel etc., use the following ENV variables to determine which integration may be causing the issue or to disable it entirely.
Use HONEYCOMB_DISABLE_AUTOCONFIGURE=true to stop the Beeline from requiring any of the Beeline integrations. This will still allow you to use the Beeline but without any of the automatic instrumentation.
You can also use HONEYCOMB_INTEGRATIONS=rails,faraday using a comma-separated list to only load specific integrations. This will allow you to be more selective about which automatic instrumentation integration you want to use. The available integration list is: active_support, aws, faraday, rack, rails, railtie, rake, sequel, sinatra.
The Rails framework integration will automatically insert the Rack middleware before the Rails::Rack::Logger middleware. To insert this in some other location, disable the railtie integration as defined above using the ENV variable HONEYCOMB_INTEGRATIONS. You will then need to insert the Honeycomb::Rails::Middleware into your middleware stack manually.
Below is a sample event from the Ruby Beeline. This example is an
http_server event, generated when your app handles an incoming
HTTP request.
{
"meta.beeline_version": "1.3.0",
"meta.local_hostname": "myhost",
"service_name": "my-test-app",
"meta.package": "rack",
"meta.package_version": "1.3",
"name": "http_server",
"request.route": "GET /dashboard",
"request.method": "GET",
"request.path": "/dashboard",
"request.protocol": "https",
"request.http_version": "HTTP/1.1",
"request.host": "my-test-app.example.com",
"request.remote_addr": "192.168.1.5",
"request.header.user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36",
"trace.trace_id": "b694512a-833f-4b35-be5f-6c742ba18e12",
"trace.span_id": "c35cc326-ed90-4881-a4a8-68526d252f2e",
"response.status_code": 200,
"duration_ms": 303.057396
}
Here are some examples to get you started querying your app’s behavior:
GROUP BY: request.pathVISUALIZE: P99(duration_ms)WHERE: name = http_requestORDER BY: P99(duration_ms) DESC
GROUP BY: nameVISUALIZE: SUM(duration_ms)ORDER BY: SUM(duration_ms) DESC
user.email) 🔗 GROUP BY: app.user.emailVISUALIZE: COUNTWHERE: request.path == /my/deprecated/endpoint
Bug fixes and other changes to Beelines are gladly accepted. Please open issues or a pull request with your change via GitHub. Remember to add your name to the CONTRIBUTORS file!
All contributions will be released under the Apache License 2.0.