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


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

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     = 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_responsesObject (readonly)

Returns the value of attribute block_on_responses.


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

def block_on_responses
  @block_on_responses
end

#block_on_sendObject (readonly)

Returns the value of attribute block_on_send.


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

def block_on_send
  @block_on_send
end

#max_batch_sizeObject (readonly)

Returns the value of attribute max_batch_size.


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

def max_batch_size
  @max_batch_size
end

#max_concurrent_batchesObject (readonly)

Returns the value of attribute max_concurrent_batches.


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

def max_concurrent_batches
  @max_concurrent_batches
end

#pending_work_capacityObject (readonly)

Returns the value of attribute pending_work_capacity.


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

def pending_work_capacity
  @pending_work_capacity
end

#responsesObject (readonly)

Returns the value of attribute responses.


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

def responses
  @responses
end

#send_frequencyObject (readonly)

Returns the value of attribute send_frequency.


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

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


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

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.


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

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


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

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.


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

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.


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

def send_dropped_response(event, msg)
  response = Response.new(error: msg,
                          metadata: event.)
  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


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

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.


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

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.


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

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