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:
- An instance of the library (in the Ruby SDK this is spelled Libhoney::Client)
- Events that are sent to honeycomb
- Builders for generating events that share common fields
- 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.