Announcing Native Ruby Support for Honeycomb

Announcing Native Ruby Support for Honeycomb

 

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.