Blog

Announcing Native Ruby Support for Honeycomb

By | 2016.11.14
 

Today we’re open sourcing our SDK for Ruby, so you can gain the same sort of insight into the behavior of your Ruby apps & services as people are already experiencing with Go, Python, and Javascript.

Install the Gem

The library is available from rubygems. To get started, add this line to your Gemfile:

gem "libhoney", "~> 1.0"

If you’d rather track the bleeding edge, you can reference our git repo directly:

gem "libhoney", :git => "https://github.com/honeycombio/libhoney-rb.git"

API Structure

The Ruby API shares the same basic structure of our other SDKs, with objects representing:

  1. An instance of the library (in the Ruby SDK this is spelled Libhoney::Client)
  2. Events that are sent to honeycomb
  3. Builders for generating events that share common fields
  4. Responses

Initializing the library

To get an instance of Libhoney::Client:

require 'libhoney'
...

libhoney = Libhoney::Client.new(:writekey => "my_writekey",
                                :dataset => "my_dataset")

Sending events

ev = libhoney.event # create an event object
ev.add_field("response_time_ms", 0.5) # add a single field/value
ev.add({ field1 => val1,
         field2 => val2 }) # add multiple fields/values at once
ev.sample_rate = 5 # optionally set the sample rate
ev.send

# the event methods are chainable, so you can also do:
libhoney.event
  .add({ field1 => val1,
         field2 => val2})
  .send

Using builders

You can use a builder to create many similar events as follows:

# create a builder for fields that will be shared
builder = libhoney.builder
builder.add_field("session_id", "012345abcdef")

# then any event created from this builder will inherit the session_id field
builder.event
  .add_field("database_ms", 0.5)
  .send
builder.event
  .add_field("external_service_roundtrip_status", 500)
  .send

The Libhoney::Client instance also acts as a builder. Builders can be created from other builders, with fields being inherited along the way:

# add a field to the libhoney builder
libhoney.add_field("user_agent", "Mozilla/5.0 ...")

# create a sub-builder from libhoney, which will inherit the user_agent field
builder = libhoney.builder("session_id", "012345abdef")

# so this event will contain 3 fields (user_agent, session_id, database_ms)
builder.event
  .add_field("database_ms", 0.5)
  .send

Responses

You can optionally subscribe to responses for all events sent through our API:

# on a separate thread from the part of the app sending events
resps = libhoney.responses

loop do
  resp = resps.pop()
  break if resp == nil
  puts "sending event with metadata #{resp.metadata} took 
    #{resp.duration}ms and got response code #{resp.status_code}"
end

You can also associate metadata with an individual event and it will be communicated back through the response object:

ev = builder.event
ev.metadata = 42 # can be anything, a string, a hash, etc
ev.send

response = libhoney.responses.pop()
puts response.metadata # => 42

That’s it!

For API documentation, visit rubydoc.info.
For higher level documentation, head to our docs.