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

Parameters:

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

    the Honeycomb API key with which to authenticate this request (required)

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

    the Honeycomb dataset into which to send events (required)

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

    cause libhoney to send 1 out of sample_rate events. overrides the libhoney instance’s value. (e.g. setting this to 10 will result in a 1-in-10 chance of it being successfully emitted to Honeycomb, and the Honeycomb query engine will interpret it as representative of 10 events)

  • api_host (String) (defaults to: API_HOST) —

    defaults to API_HOST, override to change the destination for these Honeycomb events.

  • transmission (Class, Object, nil) (defaults to: nil) —

    transport used to actually send events. If nil (the default), will be initialized with a TransmissionClient. If Class–for example, MockTransmissionClient–will attempt to create a new instance of that class with TransmissionClient‘s usual parameters. If Object, checks that the instance passed in implements the Transmission interface (responds to :add and :close). If the check does not succeed, a no-op NullTransmission will be used instead.

  • 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

  • pending_work_capacity (Fixnum) (defaults to: 1000) —

    defaults to 1000. If the queue of pending events exceeds 1000, this client will start dropping events.

  • proxy_config (String, Array, nil) (defaults to: nil) —

    proxy connection information nil: (default, recommended) connection proxying will be determined from any http_proxy, https_proxy, and no_proxy environment

    variables set for the process.

    String: the value must be the URI for connecting to a forwarding web proxy. Must be parsable by stdlib URI. Array: (deprecated, removal in v2.0) the value must have one and at most four elements: e.g. [‘host’, port, ‘username’, ‘password’].

    The assumption is that the TCP connection will be tunneled via HTTP, so the assumed scheme is 'http://'
'host' is required. 'port' is optional (default:80), unless a 'username' is included. 'password' is optional.

Raises:

  • (Exception) 


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
 
# File 'lib/libhoney/client.rb', line 66

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

  @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)
  @proxy_config           = parse_proxy_config(proxy_config)
  @transmission           = setup_transmission(transmission, writekey, dataset)
end

Instance Attribute Details

#block_on_responses ⇒ Object (readonly)

Returns the value of attribute block_on_responses.



108
109
110
 
# File 'lib/libhoney/client.rb', line 108

def block_on_responses
  @block_on_responses
end

#block_on_send ⇒ Object (readonly)

Returns the value of attribute block_on_send.



108
109
110
 
# File 'lib/libhoney/client.rb', line 108

def block_on_send
  @block_on_send
end

#max_batch_size ⇒ Object (readonly)

Returns the value of attribute max_batch_size.



108
109
110
 
# File 'lib/libhoney/client.rb', line 108

def max_batch_size
  @max_batch_size
end

#max_concurrent_batches ⇒ Object (readonly)

Returns the value of attribute max_concurrent_batches.



108
109
110
 
# File 'lib/libhoney/client.rb', line 108

def max_concurrent_batches
  @max_concurrent_batches
end

#pending_work_capacity ⇒ Object (readonly)

Returns the value of attribute pending_work_capacity.



108
109
110
 
# File 'lib/libhoney/client.rb', line 108

def pending_work_capacity
  @pending_work_capacity
end

#responses ⇒ Object (readonly)

Returns the value of attribute responses.



108
109
110
 
# File 'lib/libhoney/client.rb', line 108

def responses
  @responses
end

#send_frequency ⇒ Object (readonly)

Returns the value of attribute send_frequency.



108
109
110
 
# File 'lib/libhoney/client.rb', line 108

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



132
133
134
135
 
# File 'lib/libhoney/client.rb', line 132

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 })

Parameters:

  • name (String) —

    name of field to add.

  • proc (#call) —

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

Returns:

  • (self) —

    this libhoney instance.



156
157
158
159
 
# File 'lib/libhoney/client.rb', line 156

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)

Parameters:

  • name (String) —

    name of field to add.

  • val (any) —

    value of field to add.

Returns:

  • (self) —

    this Client instance



144
145
146
147
 
# File 'lib/libhoney/client.rb', line 144

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.



117
118
119
120
121
 
# File 'lib/libhoney/client.rb', line 117

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. 



197
198
199
200
201
202
203
204
205
 
# File 'lib/libhoney/client.rb', line 197

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



192
193
194
 
# File 'lib/libhoney/client.rb', line 192

def send_event(event)
  @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
}

Parameters:

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

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

Returns:

  • (self) —

    this libhoney instance.



180
181
182
183
 
# File 'lib/libhoney/client.rb', line 180

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. 



208
209
210
 
# File 'lib/libhoney/client.rb', line 208

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