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
DEFAULT_DATASET = 
'unknown_dataset'.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, 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.



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

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 'libhoney:  max_concurrent_batches must be greater than 0' if max_concurrent_batches < 1
  raise 'libhoney:  sample rate must be greater than 0'            if sample_rate < 1

  @builder = Builder.new(self, nil)

  @builder.writekey    = writekey
  @builder.dataset     = get_dataset(dataset, writekey)
  @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.



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

def block_on_responses
  @block_on_responses
end

#block_on_send ⇒ Object (readonly)

Returns the value of attribute block_on_send.



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

def block_on_send
  @block_on_send
end

#max_batch_size ⇒ Object (readonly)

Returns the value of attribute max_batch_size.



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

def max_batch_size
  @max_batch_size
end

#max_concurrent_batches ⇒ Object (readonly)

Returns the value of attribute max_concurrent_batches.



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

def max_concurrent_batches
  @max_concurrent_batches
end

#pending_work_capacity ⇒ Object (readonly)

Returns the value of attribute pending_work_capacity.



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

def pending_work_capacity
  @pending_work_capacity
end

#responses ⇒ Object (readonly)

Returns the value of attribute responses.



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

def responses
  @responses
end

#send_frequency ⇒ Object (readonly)

Returns the value of attribute send_frequency.



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

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



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

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.



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

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



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

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.



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

def close(drain = true) # rubocop:disable Style/OptionalBooleanParameter
  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. 



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

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



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

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.



174
175
176
177
 
# File 'lib/libhoney/client.rb', line 174

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. 



202
203
204
 
# File 'lib/libhoney/client.rb', line 202

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