libhoney 1.3.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6f7c1f1580ba76af6061acd5a3913cb858085d07
-  data.tar.gz: 60c311e244c43d1bc644b514d41e61e706cdebae
+SHA256:
+  metadata.gz: 930fb89e75aad3624d26e929b09d4b900a88df25ad4c0462eedd85ea5efe1091
+  data.tar.gz: 0f7584e0ca46508f3da2d74523c15126f78f230312c865c2facadcac49dcb187
 SHA512:
-  metadata.gz: 01281419d356b74b4af7d48b6cfe6fb9db346ec384f0e7326cb2eec11baba6e917f2620c47077e148f228caf86da5f3232db00b63a01fa660660b8f67675ba73
-  data.tar.gz: 68d452bc863044c530a0a36718484635d893cdf29a1c89b823edcbcda56e9faf3b85407df3c35393fe1e9ac02b2524de1cda49f98c21adc424ea15bf04b97017
+  metadata.gz: f3990fcde2ad49d87eb9503ef89ca42cc7ab03c6c6ec2527bd1ec84062496a8e3c514e7b53c09ef5a278390f778afb807a3728617e0e00de89f1b7d0c1494285
+  data.tar.gz: 4bee236b58007911ad8c1e0ced9754bc127a1629aa330903c7a40ed8452d0d8c3274ed0e2b444ae04965137a50a72ce6198e9a278fbbb2a4af5fbccba60719f5

data/README.md

@@ -59,6 +59,34 @@ honeycomb.close
 
 You can find a more complete example demonstrating usage in [`example/fact.rb`](example/fact.rb)
 
+## Testing instrumented code
+
+Once you've instrumented your code to send events to Honeycomb, you may want to
+consider writing tests that verify your code is producing the events you expect,
+annotating them with the right information, etc. That way, if your code changes
+and breaks the instrumentation, you'll find out straight away, instead of at 3am
+when you need that data available for debugging!
+
+To support this use case, libhoney provides a
+[`TestClient`](http://www.rubydoc.info/gems/libhoney/Libhoney/TestClient) which
+you can swap in for the usual `Client`. Example usage:
+
+```ruby
+fakehoney = Libhoney::TestClient.new
+
+my_app = MyApp.new(..., fakehoney, ...)
+my_app.do_stuff
+
+expect(fakehoney.events.size).to eq 3
+
+first_event = fakehoney.events[0]
+expect(first_event.data['hovercraft_contents']).to eq 'Eels'
+```
+
+For more detail see the docs for
+[`TestClient`](http://www.rubydoc.info/gems/libhoney/Libhoney/TestClient) and
+[`Event`](http://www.rubydoc.info/gems/libhoney/Libhoney/Event).
+
 ## Contributions
 
 Features, bug fixes and other changes to libhoney are gladly accepted. Please

data/lib/libhoney/client.rb

@@ -53,12 +53,14 @@ module Libhoney
     # @param dataset [String] the dataset you want
     # @param sample_rate [Fixnum] cause libhoney to send 1 out of sampleRate events.  overrides the libhoney instance's value.
     # @param api_host [String] the base url to send events to
+    # @param transmission [Object] transport used to actually send events. If nil (the default), will be lazily initialized with a {TransmissionClient} on first event send.
     # @param block_on_send [Boolean] if more than pending_work_capacity events are written, block sending further events
     # @param block_on_responses [Boolean] if true, block if there is no thread reading from the response queue
     def initialize(writekey: '',
                    dataset: '',
                    sample_rate: 1,
                    api_host: 'https://api.honeycomb.io/',
+                   transmission: nil,
                    block_on_send: false,
                    block_on_responses: false,
                    max_batch_size: 50,
@@ -83,7 +85,7 @@ module Libhoney
       @max_concurrent_batches = max_concurrent_batches
       @pending_work_capacity = pending_work_capacity
       @responses = SizedQueue.new(2 * @pending_work_capacity)
-      @tx = nil
+      @tx = transmission
       @lock = Mutex.new
 
       self
@@ -203,6 +205,23 @@ module Libhoney
     def should_drop(sample_rate)
       rand(1..sample_rate) != 1
     end
+  end
 
+  # A client with the network stubbed out for testing purposes. Does not
+  # actually send any events to Honeycomb; instead, records events for later
+  # inspection.
+  #
+  # @note This class is intended for use in tests, for example if you want to
+  #       verify what events your instrumented code is sending. Use in
+  #       production is not recommended.
+  class TestClient < Client
+    def initialize(*args, **kwargs)
+      super(*args, transmission: MockTransmissionClient.new, **kwargs)
+    end
+
+    # @return [Array<Event>] the recorded events
+    def events
+      @tx.events
+    end
   end
 end

data/lib/libhoney/event.rb

@@ -1,11 +1,11 @@
 module Libhoney
   ##
   # This is the event object that you can fill up with data.
-  # The data itself is a ruby hash.
   class Event
     attr_accessor :writekey, :dataset, :sample_rate, :api_host
     attr_accessor :timestamp, :metadata
 
+    # @return [Hash<String=>any>] the fields in this event
     attr_reader :data
     
     # @api private
@@ -92,10 +92,6 @@ module Libhoney
     # @return [self] this event.
     def send_presampled
       raise ArgumentError.new("No metrics added to event. Won't send empty event.")         if self.data.length == 0
-      raise ArgumentError.new("No APIHost for Honeycomb. Can't send to the Great Unknown.") if self.api_host == ""
-      raise ArgumentError.new("No WriteKey specified. Can't send event.")                   if self.writekey == ""
-      raise ArgumentError.new("No Dataset for Honeycomb. Can't send datasetless.")          if self.dataset == ""
-
       @libhoney.send_event(self)
       self
     end

data/lib/libhoney/mock_transmission.rb

@@ -0,0 +1,26 @@
+module Libhoney
+  # For testing use: a mock version of TransmissionClient that retains all
+  # events in an in-memory queue for inspection (and does not send them to
+  # Honeycomb, or perform any network activity).
+  #
+  # @note This class is intended for use in tests, for example if you want to
+  #       verify what events your instrumented code is sending. Use in
+  #       production is not recommended.
+  class MockTransmissionClient
+    def initialize
+      @events = []
+    end
+
+    # @return [Array<Event>] the recorded events
+    attr_reader :events
+
+    # Records an event
+    def add(event)
+      @events.push(event)
+    end
+
+    # Does nothing.
+    def close(drain)
+    end
+  end
+end

data/lib/libhoney/transmission.rb

@@ -26,6 +26,10 @@ module Libhoney
     end
 
     def add(event)
+      raise ArgumentError, "No APIHost for Honeycomb. Can't send to the Great Unknown." if event.api_host == ""
+      raise ArgumentError, "No WriteKey specified. Can't send event." if event.writekey == ""
+      raise ArgumentError, "No Dataset for Honeycomb. Can't send datasetless." if event.dataset == ""
+
       begin
         @send_queue.enq(event, !@block_on_send)
       rescue ThreadError

data/lib/libhoney/version.rb

@@ -1,3 +1,3 @@
 module Libhoney
-  VERSION = "1.3.2"
+  VERSION = "1.4.0"
 end

data/lib/libhoney.rb

@@ -3,3 +3,4 @@ require 'libhoney/version'
 require 'libhoney/builder'
 require 'libhoney/response'
 require 'libhoney/transmission'
+require 'libhoney/mock_transmission'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libhoney
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0
 platform: ruby
 authors:
 - The Honeycomb.io Team
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-10 00:00:00.000000000 Z
+date: 2017-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -127,6 +127,7 @@ files:
 - lib/libhoney/builder.rb
 - lib/libhoney/client.rb
 - lib/libhoney/event.rb
+- lib/libhoney/mock_transmission.rb
 - lib/libhoney/response.rb
 - lib/libhoney/transmission.rb
 - lib/libhoney/version.rb
@@ -151,7 +152,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.14
+rubygems_version: 2.7.2
 signing_key: 
 specification_version: 4
 summary: send data to Honeycomb