Class: Libhoney::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/libhoney/client.rb

Overview

This is a library to allow you to send events to Honeycomb from within your ruby application.

Example:

require 'libhoney'
honey = Libhoney.new(writekey, dataset, url, sample_rate, num_workers)
event = honey.event
event.add({'pglatency' => 100})
honey.send(event)
<repeat creating and sending events until your program is finished>
honey.close

Arguments:

  • writekey is the key to use the Honeycomb service

  • dataset is the dataset to write into

  • sample_rate is how many samples you want to keep. IE: 1 means you want 1 out of 1 samples kept, or all of them. 10 means you want 1 out of 10 samples kept. And so on.

  • url is the url to connect to Honeycomb

  • num_workers is the number of threads working on the queue of events you are generating

Note that by default, the max queue size is 1000. If the queue gets bigger than that, we start dropping events.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(writekey: '', dataset: '', sample_rate: 1, api_host: 'https://api.honeycomb.io/', block_on_send: false, block_on_responses: false, max_batch_size: 50, send_frequency: 100, max_concurrent_batches: 10, pending_work_capacity: 1000) ⇒ Client

Instantiates libhoney and prepares it to send events to Honeycomb.

Parameters:

  • writekey (String) (defaults to: '') —

    the write key from your honeycomb team

  • dataset (String) (defaults to: '') —

    the dataset you want

  • sample_rate (Fixnum) (defaults to: 1) —

    cause libhoney to send 1 out of sampleRate events. overrides the libhoney instance’s value.

  • api_host (String) (defaults to: 'https://api.honeycomb.io/') —

    the base url to send events to

  • block_on_send (Boolean) (defaults to: false) —

    if more than pending_work_capacity events are written, block sending further events

  • block_on_responses (Boolean) (defaults to: false) —

    if true, block if there is no thread reading from the response queue

Raises:

  • (Exception) 


58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/libhoney/client.rb', line 58

def initialize(writekey: '',
               dataset: '',
               sample_rate: 1,
               api_host: 'https://api.honeycomb.io/',
               block_on_send: false,
               block_on_responses: false,
               max_batch_size: 50,
               send_frequency: 100,
               max_concurrent_batches: 10,
               pending_work_capacity: 1000)
  # check for insanity
  raise Exception.new('libhoney:  max_concurrent_batches must be greater than 0') if max_concurrent_batches < 1
  raise Exception.new('libhoney:  sample rate must be greater than 0') if sample_rate < 1

  raise Exception.new("libhoney:  Ruby versions < 2.2 are not supported") if !Gem::Dependency.new("ruby", "~> 2.2").match?("ruby", RUBY_VERSION)      
  @builder = Builder.new(self, nil)
  @builder.writekey = writekey
  @builder.dataset = dataset
  @builder.sample_rate = sample_rate
  @builder.api_host = api_host

  @block_on_send = block_on_send
  @block_on_responses = block_on_responses
  @max_batch_size = max_batch_size
  @send_frequency = send_frequency
  @max_concurrent_batches = max_concurrent_batches
  @pending_work_capacity = pending_work_capacity
  @responses = SizedQueue.new(2 * @pending_work_capacity)
  @tx = nil
  @lock = Mutex.new

  self
end

Instance Attribute Details

#block_on_responses ⇒ Object (readonly)

Returns the value of attribute block_on_responses.



94
95
96
 
# File 'lib/libhoney/client.rb', line 94

def block_on_responses
  @block_on_responses
end

#block_on_send ⇒ Object (readonly)

Returns the value of attribute block_on_send.



94
95
96
 
# File 'lib/libhoney/client.rb', line 94

def block_on_send
  @block_on_send
end

#max_batch_size ⇒ Object (readonly)

Returns the value of attribute max_batch_size.



94
95
96
 
# File 'lib/libhoney/client.rb', line 94

def max_batch_size
  @max_batch_size
end

#max_concurrent_batches ⇒ Object (readonly)

Returns the value of attribute max_concurrent_batches.



94
95
96
 
# File 'lib/libhoney/client.rb', line 94

def max_concurrent_batches
  @max_concurrent_batches
end

#pending_work_capacity ⇒ Object (readonly)

Returns the value of attribute pending_work_capacity.



94
95
96
 
# File 'lib/libhoney/client.rb', line 94

def pending_work_capacity
  @pending_work_capacity
end

#responses ⇒ Object (readonly)

Returns the value of attribute responses.



94
95
96
 
# File 'lib/libhoney/client.rb', line 94

def responses
  @responses
end

#send_frequency ⇒ Object (readonly)

Returns the value of attribute send_frequency.



94
95
96
 
# File 'lib/libhoney/client.rb', line 94

def send_frequency
  @send_frequency
end

Instance Method Details

#add(data) ⇒ self

adds a group of field->values to the global Builder.

Examples:

honey.add {
  :responseTime_ms => 100,
  :httpStatusCode => 200
}

Parameters:

  • data (Hash<String=>any>) —

    field->value mapping.

Returns:

  • (self) —

    this Client instance



124
125
126
127
 
# File 'lib/libhoney/client.rb', line 124

def add(data)
  @builder.add(data)
  self
end

#add_dynamic_field(name, fn) ⇒ self

adds a single field->dynamic value function to the global Builder.

Examples:

honey.addDynamicField("active_threads", Proc.new { Thread.list.select {|thread| thread.status == "run"}.count })

Parameters:

  • name (String) —

    name of field to add.

  • fn (#call) —

    function that will be called to generate the value whenever an event is created.

Returns:

  • (self) —

    this libhoney instance.



148
149
150
151
 
# File 'lib/libhoney/client.rb', line 148

def add_dynamic_field(name, fn)
  @builder.add_dynamic_field(name, fn)
  self
end

#add_field(name, val) ⇒ self

adds a single field->value mapping to the global Builder.

Examples:

honey.addField("responseTime_ms", 100)

Parameters:

  • name (String) —

    name of field to add.

  • val (any) —

    value of field to add.

Returns:

  • (self) —

    this Client instance



136
137
138
139
 
# File 'lib/libhoney/client.rb', line 136

def add_field(name, val)
  @builder.add_field(name, val)
  self
end

#builder(fields = {}, dyn_fields = {}) ⇒ Object 



102
103
104
 
# File 'lib/libhoney/client.rb', line 102

def builder(fields = {}, dyn_fields = {})
  @builder.builder(fields, dyn_fields)
end

#close(drain = false) ⇒ Object

Nuke the queue and wait for inflight requests to complete before returning. If you set drain=true, it will not clear the queue, so all queued requests will drain before exiting.



110
111
112
113
 
# File 'lib/libhoney/client.rb', line 110

def close(drain=false)
  return @tx.close(drain) if @tx
  0
end

#event ⇒ Object 



98
99
100
 
# File 'lib/libhoney/client.rb', line 98

def event
  @builder.event
end

#send_dropped_response(event, msg) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



193
194
195
196
197
198
199
200
201
 
# File 'lib/libhoney/client.rb', line 193

def send_dropped_response(event, msg)
  response = Response.new(:error => msg,
                          :metadata => event.metadata)
  begin
    @responses.enq(response, !@block_on_responses)
  rescue ThreadError
    # happens if the queue was full and block_on_responses = false.
  end
end

#send_event(event) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Enqueue an event to send. Sampling happens here, and we will create new threads to handle work as long as we haven’t gone over max_concurrent_batches and there are still events in the queue.

Parameters:

  • event (Event) —

    the event to send to honeycomb



176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/libhoney/client.rb', line 176

def send_event(event)
  @lock.synchronize {
    if !@tx
      @tx = TransmissionClient.new(:max_batch_size => @max_batch_size,
                                   :send_frequency => @send_frequency,
                                   :max_concurrent_batches => @max_concurrent_batches,
                                   :pending_work_capacity => @pending_work_capacity,
                                   :responses => @responses,
                                   :block_on_send => @block_on_send,
                                   :block_on_responses => @block_on_responses)
    end
  }

  @tx.add(event)
end

#send_now(data = {}) ⇒ self

creates and sends an event, including all global builder fields/dyn_fields, as well as anything in the optional data parameter.

/

Examples:

empty sendNow

honey.sendNow() # sends just the data that has been added via add/add_field/add_dynamic_field.

adding data at send-time

honey.sendNow {
  additionalField: value
}

Parameters:

  • data (Hash<String=>any>) (defaults to: {}) —

    optional field->value mapping to add to the event sent.

Returns:

  • (self) —

    this libhoney instance.



164
165
166
167
 
# File 'lib/libhoney/client.rb', line 164

def send_now(data = {})
  @builder.send_now(data)
  self
end

#should_drop(sample_rate) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



204
205
206
 
# File 'lib/libhoney/client.rb', line 204

def should_drop(sample_rate)
  rand(1..sample_rate) != 1
end