libhoney 1.18.0 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33a687ebf8ae87e69cf6a53b50c4e2cd926f9938af709635d42a209ec2e6c93e
-  data.tar.gz: fd3f558a15f872c9f63fc6451722c3e9e21b7cba5ebe8d7816ec0cb08064318b
+  metadata.gz: 40d54151fc103bf8020f14ff8b7a9e6e0298366869e795ce3ddf0438af066e16
+  data.tar.gz: c2b834d39609a73bce6e5e6e19caf4d2499903498895d32fe22b55041db7e59b
 SHA512:
-  metadata.gz: 36efc5d9734e125cd141e21dd60edbc6cf23350334bf431dead264c375dfd11b54bcf286f5509d5e97633ee4ce2d4fc689ebf5033d472237d5b6e7e2f2d0cb81
-  data.tar.gz: 5d5147a6e9f3fc1055a94932943c5915c99f43ad550d4dd5f20955d2dad023c41a1939e6f8037b38856375a10dcdc51557b06e3d56b454296a1596c7dd62b74c
+  metadata.gz: 24d9d44cb0f1f5ad7549b75067dd6cbc2eb2264b8cad1c1c8cf523c19d955e41b91feb86d6cde74104885fc61ee4c4f5309b3ed46edfc5751483ba282d5e841e
+  data.tar.gz: 1b1690d32daf8f44a19761d2ccc26a5a099d1daec623ecd481776f34ea439506278c267ff8b319c0ccb380ec497ca1de4b6e9c2a7eee677a1584d9d1cfe1ec87

data/.circleci/config.yml

@@ -97,6 +97,8 @@ jobs:
       - run:
           name: run tests
           command: bundle exec rake test
+      - store_test_results:
+          path: test/reports
 
   build_artifacts:
     executor:

data/.github/CODEOWNERS

@@ -2,4 +2,4 @@
 # This file controls who is tagged for review for any given pull request.
 
 # For anything not explicitly taken by someone else:
-* @honeycombio/integrations-team @martin308
+* @honeycombio/telemetry-team

data/.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "bundler" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    labels:
+      - "type: dependencies"
+    reviewers:
+      - "honeycombio/telemetry-team"

data/.github/workflows/add-to-project.yml

@@ -0,0 +1,14 @@
+name: Apply project management flow
+on:
+  issues:
+    types: [opened]
+  pull_request_target:
+    types: [opened]
+jobs:
+  project-management:
+    runs-on: ubuntu-latest
+    name: Apply project management flow
+    steps:
+      - uses: honeycombio/oss-management-actions/projects@v1
+        with:
+          ghprojects-token: ${{ secrets.GHPROJECTS_TOKEN }}

data/.github/workflows/apply-labels.yml

@@ -0,0 +1,10 @@
+name: Apply project labels
+on: [issues, pull_request, label]
+jobs:
+  apply-labels:
+    runs-on: ubuntu-latest
+    name: Apply common project labels
+    steps:
+      - uses: honeycombio/oss-management-actions/labels@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

data/.gitignore

@@ -7,6 +7,7 @@
 /pkg/
 /spec/reports/
 /spec/examples.txt
+/test/reports/
 /test/tmp/
 /test/version_tmp/
 /tmp/

data/.rubocop.yml

@@ -9,18 +9,19 @@ Style/Documentation:
 Lint/RescueException:
   Exclude:
     - 'lib/libhoney/transmission.rb'
+    - 'lib/libhoney/experimental_transmission.rb'
 
 Metrics/BlockLength:
   Max: 35
 
 Metrics/ClassLength:
-  Max: 200
+  Max: 300
   Exclude:
     - lib/libhoney/transmission.rb # Should this remain so large?
     - test/*
 
 Metrics/MethodLength:
-  Max: 40
+  Max: 45
   Exclude:
     - lib/libhoney/transmission.rb
     - test/*

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## changes pending release
 
+## 1.19.0
+
+### Improvements
+
+- add a test_helper, Minitest reporters, & store test results in CI (#88)
+- add experimental transmission with new sized-and-timed queue (#87)
+
+### Fixes
+
+- Process single-error responses from the Batch API (#89)
+
 ## 1.18.0
 
 ### Improvements

data/lib/libhoney/client.rb

@@ -46,7 +46,11 @@ module Libhoney
     #   Honeycomb query engine will interpret it as representative of 10 events)
     # @param api_host [String] defaults to +API_HOST+, override to change the
     #   destination for these Honeycomb events.
-    # @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 transmission [Class, Object, 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.
     # @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
     # @param pending_work_capacity [Fixnum] defaults to 1000. If the queue of
@@ -88,17 +92,6 @@ module Libhoney
       @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
@@ -108,8 +101,8 @@ module Libhoney
       @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)
+      @transmission           = setup_transmission(transmission, writekey, dataset)
     end
 
     attr_reader :block_on_send, :block_on_responses, :max_batch_size,
@@ -197,22 +190,6 @@ module Libhoney
     # @param event [Event] the event to send to honeycomb
     # @api private
     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
 
@@ -234,6 +211,57 @@ module Libhoney
 
     private
 
+    ##
+    # Parameters to pass to a transmission based on client config.
+    #
+    def 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
+      }
+    end
+
+    def setup_transmission(transmission, writekey, dataset)
+      # if a provided transmission can add and close, we'll assume the user
+      # has provided a working transmission with a customized configuration
+      return transmission if quacks_like_a_transmission?(transmission)
+
+      if !(writekey && dataset) # rubocop:disable Style/NegatedIf
+        # 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"
+        return NullTransmissionClient.new
+      end
+
+      case transmission
+      when NilClass # the default value for new clients
+        return TransmissionClient.new(**transmission_client_params)
+      when Class
+        # if a class has been provided, attempt to instantiate it with parameters given to the client
+        t = transmission.new(**transmission_client_params)
+        if quacks_like_a_transmission?(t) # rubocop:disable Style/GuardClause
+          return t
+        else
+          warn "#{t.class.name}: does not appear to behave like a transmission, disabling sending events"
+          return NullTransmissionClient.new
+        end
+      end
+    end
+
+    def quacks_like_a_transmission?(transmission)
+      transmission.respond_to?(:add) && transmission.respond_to?(:close)
+    end
+
     # @api private
     def parse_proxy_config(config)
       case config

data/lib/libhoney/experimental_transmission.rb

@@ -0,0 +1,109 @@
+require 'libhoney/queueing'
+require 'libhoney/transmission'
+
+module Libhoney
+  ##
+  # An experimental variant of the standard {TransmissionClient} that uses
+  # a custom implementation of a sized queue whose pop/push methods support
+  # a timeout internally.
+  #
+  # @example Use this transmission with the Ruby Beeline
+  #   require 'libhoney/experimental_transmission'
+  #
+  #   Honeycomb.configure do |config|
+  #     config.client = Libhoney::Client.new(
+  #       writekey: ENV["HONEYCOMB_WRITE_KEY"],
+  #       dataset: ENV.fetch("HONEYCOMB_DATASET", "awesome_sauce"),
+  #       transmission: Libhoney::ExperimentalTransmissionClient
+  #     )
+  #     ...
+  #   end
+  #
+  # @api private
+  #
+  class ExperimentalTransmissionClient < TransmissionClient
+    def add(event)
+      return unless event_valid(event)
+
+      begin
+        # if block_on_send is true, never timeout the wait to enqueue an event
+        # otherwise, timeout the wait immediately and if the queue is full, we'll
+        # have a ThreadError raised because we could not add to the queue.
+        timeout = @block_on_send ? :never : 0
+        @batch_queue.enq(event, timeout)
+      rescue Libhoney::Queueing::SizedQueueWithTimeout::PushTimedOut
+        # happens if the queue was full and block_on_send = false.
+        warn "#{self.class.name}: batch queue full, dropping event." if %w[debug trace].include?(ENV['LOG_LEVEL'])
+      end
+
+      ensure_threads_running
+    end
+
+    def batch_loop
+      next_send_time = Time.now + @send_frequency
+      batched_events = Hash.new do |h, key|
+        h[key] = []
+      end
+
+      loop do
+        begin
+          # an event on the batch_queue
+          #   1. pops out and is truthy
+          #   2. gets included in the current batch
+          #   3. while waits for another event
+          while (event = @batch_queue.pop(@send_frequency))
+            key = [event.api_host, event.writekey, event.dataset]
+            batched_events[key] << event
+          end
+
+          # a nil on the batch_queue
+          #   1. pops out and is falsy
+          #   2. ends the event-popping while do..end
+          #   3. breaks the loop
+          #   4. flushes the current batch
+          #   5. ends the batch_loop
+          break
+
+        # a timeout expiration waiting for an event
+        #   1. skips the break and is rescued
+        #   2. triggers the ensure to flush the current batch
+        #   3. begins the loop again with an updated next_send_time
+        rescue Libhoney::Queueing::SizedQueueWithTimeout::PopTimedOut => e
+          warn "#{self.class.name}: ⏱ " + e.message if %w[trace].include?(ENV['LOG_LEVEL'])
+
+        # any exception occurring in this loop should not take down the actual
+        # instrumented Ruby process, so handle here and log that there is trouble
+        rescue Exception => e
+          warn "#{self.class.name}: 💥 " + e.message if %w[debug trace].include?(ENV['LOG_LEVEL'])
+          warn e.backtrace.join("\n").to_s if ['trace'].include?(ENV['LOG_LEVEL'])
+
+        # regardless of the exception, figure out whether enough time has passed to
+        # send the current batched events, if so, send them and figure out the next send time
+        # before going back to the top of the loop
+        ensure
+          next_send_time = flush_batched_events(batched_events) if Time.now > next_send_time
+        end
+      end
+
+      # don't need to capture the next_send_time here because the batch_loop is exiting
+      # for some reason (probably transmission.close)
+      flush_batched_events(batched_events)
+    end
+
+    private
+
+    def setup_batch_queue
+      # override super()'s @batch_queue = SizedQueue.new(); use our SizedQueueWithTimeout:
+      # + block on adding events to the batch_queue when queue is full and @block_on_send is true
+      # + the queue knows how to limit size and how to time-out pushes and pops
+      @batch_queue = Libhoney::Queueing::SizedQueueWithTimeout.new(@pending_work_capacity)
+      warn "⚠️🐆 #{self.class.name} in use! It may drop data, consume all your memory, or cause skin irritation."
+    end
+
+    def build_user_agent(user_agent_addition)
+      ua = "libhoney-rb/#{VERSION} (exp-transmission)"
+      ua << " #{user_agent_addition}" if user_agent_addition
+      ua
+    end
+  end
+end

data/lib/libhoney/mock_transmission.rb

@@ -7,7 +7,7 @@ module Libhoney
   #       verify what events your instrumented code is sending. Use in
   #       production is not recommended.
   class MockTransmissionClient
-    def initialize
+    def initialize(**_)
       reset
     end
 

data/lib/libhoney/null_transmission.rb

@@ -4,6 +4,8 @@ module Libhoney
   #
   # @api private
   class NullTransmissionClient
+    def initialize(**_); end
+
     def add(event); end
 
     def close(drain); end

data/lib/libhoney/queueing.rb

@@ -0,0 +1 @@
+require 'libhoney/queueing/sized_queue_with_timeout'

data/lib/libhoney/queueing/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2021 Honeycomb
+Copyright (c) 2013 Avdi Grimm
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/libhoney/queueing/sized_queue_with_timeout.rb

@@ -0,0 +1,176 @@
+##
+# SizedQueueWithTimeout is copyright and licensed per the LICENSE.txt in
+# its containing subdirectory of this codebase.
+#
+module Libhoney
+  module Queueing
+    ##
+    # A queue implementation with optional size limit and optional timeouts on pop and push
+    # operations. Heavily influenced / liberally mimicking Avdi Grimm's
+    # {Tapas::Queue}[https://github.com/avdi/tapas-queue].
+    #
+    class SizedQueueWithTimeout
+      class PushTimedOut < ThreadError; end
+      class PopTimedOut < ThreadError; end
+
+      ##
+      # @param max_size [Integer, Float::INFINITY] the size limit for this queue
+      # @param options [Hash] optional dependencies to inject, primarily for testing
+      # @option options [QLock, Mutex] :lock the lock for synchronizing queue state change
+      # @option options [QCondition] :space_available_condition the condition variable
+      #   to wait/signal on for space being available in the queue; when provided, must
+      #   be accompanied by an +:item_available_condition+ and the shared +:lock+
+      # @option options [QCondition] :item_available_condition the condition variable
+      #   to wait/signal on for an item being added to the queue; when provided, must
+      #   be accompanied by an +:space_available_condition+ and the shared +:lock+
+      def initialize(max_size = Float::INFINITY, options = {})
+        @items           = []
+        @max_size        = max_size
+        @lock            = options.fetch(:lock) { QLock.new }
+        @space_available = options.fetch(:space_available_condition) { QCondition.new(@lock) }
+        @item_available  = options.fetch(:item_available_condition) { QCondition.new(@lock) }
+      end
+
+      ##
+      # Push something onto the queue.
+      #
+      # @param obj [Object] the thing to add to the queue
+      # @param timeout [Numeric, :never] how long in seconds to wait for the queue to have space available or
+      #   +:never+ to wait "forever"
+      # @param timeout_policy [#call] defaults to +-> { raise PushTimedOut }+ - a lambda/Proc/callable, what to do
+      #   when the timeout expires
+      #
+      # @raise {PushTimedOut}
+      def push(obj, timeout = :never, &timeout_policy)
+        timeout_policy ||= -> { raise PushTimedOut }
+
+        wait_for_condition(@space_available, -> { !full? }, timeout, timeout_policy) do
+          @items.push(obj)
+          @item_available.signal
+        end
+      end
+      alias enq push
+      alias << push
+
+      ##
+      # Pop something off the queue.
+      #
+      # @param timeout [Numeric, :never] how long in seconds to wait for the queue to have an item available or
+      #   +:never+ to wait "forever"
+      # @param timeout_policy [#call] defaults to +-> { raise PopTimedOut }+ - a lambda/Proc/callable, what to do
+      #   when the timeout expires
+      #
+      # @return [Object]
+      # @raise {PopTimedOut}
+      def pop(timeout = :never, &timeout_policy)
+        timeout_policy ||= -> { raise PopTimedOut }
+
+        wait_for_condition(@item_available, -> { !empty? }, timeout, timeout_policy) do
+          item = @items.shift
+          @space_available.signal unless full?
+          item
+        end
+      end
+      alias deq pop
+      alias shift pop
+
+      ##
+      # Removes all objects from the queue. They are cast into the abyss never to be seen again.
+      #
+      def clear
+        @lock.synchronize do
+          @items = []
+          @space_available.signal unless full?
+        end
+      end
+
+      private
+
+      ##
+      # Whether the queue is at capacity. Must be called with the queue's lock
+      # or the answer won't matter if you try to change state based on it.
+      #
+      # @return [true/false]
+      # @api private
+      def full?
+        @max_size <= @items.size
+      end
+
+      ##
+      # Whether the queue is empty. Must be called with the queue's lock or the
+      # answer won't matter if you try to change state based on it.
+      #
+      # @return [true/false]
+      # @api private
+      def empty?
+        @items.empty?
+      end
+
+      # a generic conditional variable wait with a timeout loop
+      #
+      # @param condition [#wait] a condition variable to wait upon.
+      # @param condition_predicate [#call] a callable (i.e. lambda or proc) that returns true/false to act
+      #   as a state tester (i.e. "is the queue currently empty?") to check on whether to keep waiting;
+      #   used to handle spurious wake ups occurring before the timeout has elapsed
+      # @param timeout [:never, Numeric] the amount of time in (seconds?) to wait, or :never to wait forever
+      # @param timeout_policy [#call] a callable, what to do when a timeout occurs? Return a default? Raise an
+      #   exception? You decide.
+      def wait_for_condition(condition, condition_predicate, timeout = :never, timeout_policy = -> { nil })
+        deadline = timeout == :never ? :never : trustworthy_current_time + timeout
+        @lock.synchronize do
+          loop do
+            time_remaining = timeout == :never ? nil : deadline - trustworthy_current_time
+
+            if !condition_predicate.call && time_remaining.to_f >= 0 # rubocop:disable Style/IfUnlessModifier
+              condition.wait(time_remaining)
+            end
+
+            if condition_predicate.call # rubocop:disable Style/GuardClause
+              return yield
+            elsif deadline == :never || deadline > trustworthy_current_time
+              next
+            else
+              return timeout_policy.call
+            end
+          end
+        end
+      end
+
+      # Within the context of the current process, return time from a
+      # monotonically increasing clock because for timeouts we care about
+      # elapsed time within the process, not human time.
+      #
+      # @return [Numeric]
+      def trustworthy_current_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    class QCondition
+      def initialize(lock)
+        @lock = lock
+        @cv   = ConditionVariable.new
+      end
+
+      def wait(timeout = nil)
+        @cv.wait(@lock.mutex, timeout)
+      end
+
+      def signal
+        @cv.signal
+      end
+    end
+
+    class QLock
+      attr_reader :mutex
+
+      def initialize
+        @mutex = Mutex.new
+      end
+
+      def synchronize(&block)
+        @mutex.synchronize(&block)
+      end
+    end
+  end
+end

data/lib/libhoney/transmission.rb

@@ -36,9 +36,9 @@ module Libhoney
       @send_queue   = Queue.new
       @threads      = []
       @lock         = Mutex.new
-      # use a SizedQueue so the producer will block on adding to the batch_queue when @block_on_send is true
-      @batch_queue  = SizedQueue.new(@pending_work_capacity)
       @batch_thread = nil
+
+      setup_batch_queue
     end
 
     def add(event)
@@ -53,26 +53,6 @@ module Libhoney
       ensure_threads_running
     end
 
-    def event_valid(event)
-      invalid = []
-      invalid.push('api host') if event.api_host.nil? || event.api_host.empty?
-      invalid.push('write key') if event.writekey.nil? || event.writekey.empty?
-      invalid.push('dataset') if event.dataset.nil? || event.dataset.empty?
-
-      unless invalid.empty?
-        e = StandardError.new("#{self.class.name}: nil or empty required fields (#{invalid.join(', ')})"\
-          '. Will not attempt to send.')
-        Response.new(error: e).tap do |error_response|
-          error_response.metadata = event.metadata
-          enqueue_response(error_response)
-        end
-
-        return false
-      end
-
-      true
-    end
-
     def send_loop
       http_clients = build_http_clients
 
@@ -133,23 +113,31 @@ module Libhoney
     end
 
     def close(drain)
-      # if drain is false, clear the remaining unprocessed events from the queue
-      unless drain
-        @batch_queue.clear
-        @send_queue.clear
-      end
+      @lock.synchronize do
+        # if drain is false, clear the remaining unprocessed events from the queue
+        if drain
+          warn "#{self.class.name} - close: draining events" if %w[debug trace].include?(ENV['LOG_LEVEL'])
+        else
+          warn "#{self.class.name} - close: deleting unsent events" if %w[debug trace].include?(ENV['LOG_LEVEL'])
+          @batch_queue.clear
+          @send_queue.clear
+        end
 
-      @batch_queue.enq(nil)
-      @batch_thread.join unless @batch_thread.nil?
+        @batch_queue.enq(nil)
+        if @batch_thread.nil?
+        else
+          @batch_thread.join(1.0) # limit the amount of time we'll wait for the thread to end
+        end
 
-      # send @threads.length number of nils so each thread will fall out of send_loop
-      @threads.length.times { @send_queue << nil }
+        # send @threads.length number of nils so each thread will fall out of send_loop
+        @threads.length.times { @send_queue << nil }
 
-      @threads.each(&:join)
-      @threads = []
+        @threads.each(&:join)
+        @threads = []
+      end
 
       enqueue_response(nil)
-
+      warn "#{self.class.name} - close: close complete" if %w[debug trace].include?(ENV['LOG_LEVEL'])
       0
     end
 
@@ -161,25 +149,76 @@ module Libhoney
 
       loop do
         begin
+          # a timeout expiration waiting for an event
+          #   1. interrupts only when thread is in a blocking state (waiting for pop)
+          #   2. exception skips the break and is rescued
+          #   3. triggers the ensure to flush the current batch
+          #   3. begins the loop again with an updated next_send_time
           Thread.handle_interrupt(Timeout::Error => :on_blocking) do
+            # an event on the batch_queue
+            #   1. pops out and is truthy
+            #   2. gets included in the current batch
+            #   3. while waits for another event
             while (event = Timeout.timeout(@send_frequency) { @batch_queue.pop })
               key = [event.api_host, event.writekey, event.dataset]
               batched_events[key] << event
             end
           end
 
+          # a nil on the batch_queue
+          #   1. pops out and is falsy
+          #   2. ends the event-popping while do..end
+          #   3. breaks the loop
+          #   4. flushes the current batch
+          #   5. ends the batch_loop
           break
-        rescue Exception
+        rescue Exception => e
+          warn "#{self.class.name}: 💥 " + e.message if %w[debug trace].include?(ENV['LOG_LEVEL'])
+          warn e.backtrace.join("\n").to_s if ['trace'].include?(ENV['LOG_LEVEL'])
+
+        # regardless of the exception, figure out whether enough time has passed to
+        # send the current batched events, if so, send them and figure out the next send time
+        # before going back to the top of the loop
         ensure
           next_send_time = flush_batched_events(batched_events) if Time.now > next_send_time
         end
       end
 
+      # don't need to capture the next_send_time here because the batch_loop is exiting
+      # for some reason (probably transmission.close)
       flush_batched_events(batched_events)
     end
 
     private
 
+    def setup_batch_queue
+      # use a SizedQueue so the producer will block on adding to the batch_queue when @block_on_send is true
+      @batch_queue = SizedQueue.new(@pending_work_capacity)
+    end
+
+    REQUIRED_EVENT_FIELDS = %i[api_host writekey dataset].freeze
+
+    def event_valid(event)
+      missing_required_fields = REQUIRED_EVENT_FIELDS.select do |required_field|
+        event.public_send(required_field).nil? || event.public_send(required_field).empty?
+      end
+
+      if missing_required_fields.empty?
+        true
+      else
+        enqueue_response(
+          Response.new(
+            metadata: event.metadata,
+            error: StandardError.new(
+              "#{self.class.name}: nil or empty required fields (#{missing_required_fields.join(', ')})"\
+              '. Will not attempt to send.'
+            )
+          )
+        )
+        false
+      end
+    end
+
     ##
     # Enqueues a response to the responses queue suppressing ThreadError when
     # there is no space left on the queue and we are not blocking on response
@@ -190,15 +229,36 @@ module Libhoney
     end
 
     def process_response(http_response, before, batch)
-      index = 0
-      JSON.parse(http_response.body).each do |event|
-        index += 1 while batch[index].nil? && index < batch.size
-        break unless (batched_event = batch[index])
-
-        Response.new(status_code: event['status']).tap do |response|
-          response.duration = Time.now - before
-          response.metadata = batched_event.metadata
-          enqueue_response(response)
+      if http_response.status == 200
+        index = 0
+        JSON.parse(http_response.body).each do |event|
+          index += 1 while batch[index].nil? && index < batch.size
+          break unless (batched_event = batch[index])
+
+          enqueue_response(
+            Response.new(
+              status_code: event['status'],
+              duration: (Time.now - before),
+              metadata: batched_event.metadata
+            )
+          )
+        end
+      else
+        error = JSON.parse(http_response.body)['error']
+        if %w[debug trace].include?(ENV['LOG_LEVEL'])
+          warn "#{self.class.name}: error sending data to Honeycomb - #{http_response.status} #{error}"
+        end
+        batch.each do |batched_event|
+          next unless batched_event # skip nils enqueued from serialization errors
+
+          enqueue_response(
+            Response.new(
+              status_code: http_response.status, # single error from API applied to all events sent in batch
+              duration: (Time.now - before),
+              metadata: batched_event.metadata,
+              error: RuntimeError.new(error)
+            )
+          )
         end
       end
     end

data/lib/libhoney/version.rb

@@ -1,3 +1,3 @@
 module Libhoney
-  VERSION = '1.18.0'.freeze
+  VERSION = '1.19.0'.freeze
 end

data/libhoney.gemspec

@@ -24,7 +24,9 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bump', '~> 0.5'
   spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'lockstep'
   spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'minitest-reporters'
   spec.add_development_dependency 'rake', '~> 12.3'
   spec.add_development_dependency 'rubocop', '< 0.69'
   spec.add_development_dependency 'sinatra'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libhoney
 version: !ruby/object:Gem::Version
-  version: 1.18.0
+  version: 1.19.0
 platform: ruby
 authors:
 - The Honeycomb.io Team
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-01-14 00:00:00.000000000 Z
+date: 2021-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bump
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: lockstep
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -222,6 +250,9 @@ files:
 - ".circleci/setup-rubygems.sh"
 - ".editorconfig"
 - ".github/CODEOWNERS"
+- ".github/dependabot.yml"
+- ".github/workflows/add-to-project.yml"
+- ".github/workflows/apply-labels.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
@@ -238,11 +269,15 @@ files:
 - lib/libhoney/cleaner.rb
 - lib/libhoney/client.rb
 - lib/libhoney/event.rb
+- lib/libhoney/experimental_transmission.rb
 - lib/libhoney/log_client.rb
 - lib/libhoney/log_transmission.rb
 - lib/libhoney/mock_transmission.rb
 - lib/libhoney/null_client.rb
 - lib/libhoney/null_transmission.rb
+- lib/libhoney/queueing.rb
+- lib/libhoney/queueing/LICENSE.txt
+- lib/libhoney/queueing/sized_queue_with_timeout.rb
 - lib/libhoney/response.rb
 - lib/libhoney/test_client.rb
 - lib/libhoney/transmission.rb
@@ -267,7 +302,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: send data to Honeycomb