Class: Libhoney::Client

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

Overview

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

Examples:

Send a simple event

require 'libhoney'
honey = Libhoney.new(writekey, dataset, sample_rate)

evt = honey.event
evt.add(pglatency: 100)
honey.send(evt)

# repeat creating and sending events until your program is finished

honey.close

Override the default timestamp on an event

one_hour_ago = Time.now - 3600

evt = libhoney.event
evt.add_fields(useful_fields)
evt.timestamp = one_hour_ago
evt.send

Direct Known Subclasses

LogClient, NullClient, TestClient

Constant Summary collapse

API_HOST = 
'https://api.honeycomb.io/'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(writekey: nil, dataset: nil, sample_rate: 1, api_host: API_HOST, user_agent_addition: nil, transmission: nil, block_on_send: false, block_on_responses: false, max_batch_size: 50, send_frequency: 100, max_concurrent_batches: 10, pending_work_capacity: 1000, proxy_config: nil) ⇒ Client

Instantiates libhoney and prepares it to send events to Honeycomb.

rubocop:disable Metrics/ParameterLists

Raises:

  • (Exception) 


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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/libhoney/client.rb', line 62

def initialize(writekey: nil,
               dataset: nil,
               sample_rate: 1,
               api_host: API_HOST,
               user_agent_addition: nil,
               transmission: nil,
               block_on_send: false,
               block_on_responses: false,
               max_batch_size: 50,
               send_frequency: 100,
               max_concurrent_batches: 10,
               pending_work_capacity: 1000,
               proxy_config: nil)
  # rubocop:enable Metrics/ParameterLists
  # check for insanity
  raise Exception, 'libhoney:  max_concurrent_batches must be greater than 0' if max_concurrent_batches < 1
  raise Exception, 'libhoney:  sample rate must be greater than 0'            if sample_rate < 1

  unless Gem::Dependency.new('ruby', '>= 2.2').match?('ruby', RUBY_VERSION)
    raise Exception, 'libhoney:  Ruby versions < 2.2 are not supported'
  end

  @builder = Builder.new(self, nil)

  @builder.writekey    = writekey
  @builder.dataset     = dataset
  @builder.sample_rate = sample_rate
  @builder.api_host    = api_host

  @transmission = transmission
  if !@transmission && !(writekey && dataset)
    # if no writekey or dataset are configured, and we didn't override the
    # transmission (e.g. to a MockTransmissionClient), that's almost
    # certainly a misconfiguration, even though it's possible to override
    # them on a per-event basis. So let's handle the misconfiguration
    # early rather than potentially throwing thousands of exceptions at runtime.
    warn "#{self.class.name}: no #{writekey ? 'dataset' : 'writekey'} configured, disabling sending events"
    @transmission = NullTransmissionClient.new
  end

  @user_agent_addition = user_agent_addition

  @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)
  @lock                   = Mutex.new
  @proxy_config           = parse_proxy_config(proxy_config)
end

Instance Attribute Details

#block_on_responses ⇒ Object (readonly)

Returns the value of attribute block_on_responses.



115
116
117
 
# File 'lib/libhoney/client.rb', line 115

def block_on_responses
  @block_on_responses
end

#block_on_send ⇒ Object (readonly)

Returns the value of attribute block_on_send.



115
116
117
 
# File 'lib/libhoney/client.rb', line 115

def block_on_send
  @block_on_send
end

#max_batch_size ⇒ Object (readonly)

Returns the value of attribute max_batch_size.



115
116
117
 
# File 'lib/libhoney/client.rb', line 115

def max_batch_size
  @max_batch_size
end

#max_concurrent_batches ⇒ Object (readonly)

Returns the value of attribute max_concurrent_batches.



115
116
117
 
# File 'lib/libhoney/client.rb', line 115

def max_concurrent_batches
  @max_concurrent_batches
end

#pending_work_capacity ⇒ Object (readonly)

Returns the value of attribute pending_work_capacity.



115
116
117
 
# File 'lib/libhoney/client.rb', line 115

def pending_work_capacity
  @pending_work_capacity
end

#responses ⇒ Object (readonly)

Returns the value of attribute responses.



115
116
117
 
# File 'lib/libhoney/client.rb', line 115

def responses
  @responses
end

#send_frequency ⇒ Object (readonly)

Returns the value of attribute send_frequency.



115
116
117
 
# File 'lib/libhoney/client.rb', line 115

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
}


139
140
141
142
 
# File 'lib/libhoney/client.rb', line 139

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

#add_dynamic_field(name, proc) ⇒ self

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

Examples:

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


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

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

#add_field(name, val) ⇒ self

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

Examples:

honey.add_field("responseTime_ms", 100)


151
152
153
154
 
# File 'lib/libhoney/client.rb', line 151

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

#close(drain = true) ⇒ Object

Nuke the queue and wait for inflight requests to complete before returning. If you set drain=false, all queued requests will be dropped on the floor.



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

def close(drain = true)
  return @transmission.close(drain) if @transmission

  0
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. 



220
221
222
223
224
225
226
227
228
 
# File 'lib/libhoney/client.rb', line 220

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.



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/libhoney/client.rb', line 199

def send_event(event)
  @lock.synchronize do
    transmission_client_params = {
      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,
      user_agent_addition: @user_agent_addition,
      proxy_config: @proxy_config
    }

    @transmission ||= TransmissionClient.new(**transmission_client_params)
  end

  @transmission.add(event)
end

#send_now(data = {}) ⇒ self

Deprecated.

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

Equivalent to:

ev = builder.event
ev.add(data)
ev.send

May be removed in a future major release

/

Examples:

empty send_now

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

adding data at send-time

honey.send_now {
  additionalField: value
}


187
188
189
190
 
# File 'lib/libhoney/client.rb', line 187

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. 



231
232
233
 
# File 'lib/libhoney/client.rb', line 231

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