logister-ruby 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b8f77ab291c0d9132dc6ea5d6f1711644d73a7892e9b7dbc4f5bb3cf418fd8f
-  data.tar.gz: 83af842795eebffcbfe29135091e89243dcd34f0e61968e8887dc75a027947f5
+  metadata.gz: 381dffab29b34b6beffe54e105fcf8dc5151f59bde1e44cfbba1749d21bff763
+  data.tar.gz: 5fe2ef7923ebeb4aa440d4aff35b246b2d407da0fe11dd26e26633e491105657
 SHA512:
-  metadata.gz: 64bdd3ca1271f84c6495883ad5dac8ca829e29ef07a5dc79391848fa344fbcf39ac757650be7356611d16b285bc45ffa561ecbc804ca0c426a887ce6593f4f57
-  data.tar.gz: 464876a85252f86ec25e507fde1a38ace3c152596756da77c682ea81a5f872d0a69b86db38404a911c42a331d932506c4162a18df60c118b10dae940542f7d19
+  metadata.gz: a5380bdc6bc4c7b4c1e4cb9e2c0d9d4cc4825f87d3517b57c22db7e63fff519071e46e9ad3555d3035819f4e1a64819d26305a1646f18cb32c02977cff925da2
+  data.tar.gz: b3d7c3a5932f560be7ec3b1dc1a88a2319799e2b166e91d8a6d6084e8d6d7eaf262c047c5d7f9ba3e095d44dc857d1ed701605ced120a2253a168d3568cc5687

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v0.4.2 - 2026-09-16
+
+- Added process-local delivery counters and an optional recursion-safe observer for queued, acknowledged, unconfirmed, queue-full, and retry outcomes without exporting event contents.
+- Clarified that a drained queue or successful `flush` does not prove every event was acknowledged; timed-out requests may already have reached the server.
+- Removed exception messages from terminal event-publish warnings to avoid exposing transport details.
+- Bounded async shutdown even when the queue is full; retained the worker until it finishes and report incomplete shutdown honestly.
+
 ## v0.4.1 - 2026-09-11
 
 - Constrained JSON to the compatible 2.x line while supported ActiveSupport 8 releases use positional JSON.parse options; verified real Rails request decoding.

data/README.md

@@ -162,6 +162,24 @@ safe against a Logister server that supports the batch endpoint. Older servers a
 detected automatically and receive the same stable events through the single-event
 endpoint. Call `Logister.flush` before a short-lived process exits.
 
+### Delivery outcomes
+
+`flush` waits for queued and in-flight attempts to finish; it does not guarantee
+server acknowledgement. Inspect `Logister.delivery_stats` for process-local
+`queued_events`, `acknowledged_events`, `unconfirmed_events`, `queue_full_events`,
+`retry_attempts`, and `pending_events`. An unconfirmed event may already have
+reached the server when its response timed out. Counts are not durable and reset
+with the client/process; they cover events, not deployment reports.
+
+For local delivery diagnostics, set `config.delivery_observer` to a fast callback
+accepting `{ outcome:, count:, reason: }`. It receives no payload, identifiers,
+credentials, or exception messages. Reporting is suppressed inside the callback
+to prevent feedback loops; callback failure cannot change delivery. Write these
+diagnostics to a local log or counter rather than publishing them through Logister.
+`shutdown` waits at most one second for the worker and returns false if attempts
+are still running. It stops accepting asynchronous events and does not kill an
+in-flight request or block while adding a sentinel to a full queue.
+
 Every HTTP attempt applies `timeout_seconds` to connect, read, and write operations.
 Retryable responses honor `Retry-After` when present, cap any individual wait at
 `max_retry_delay`, and add bounded positive jitter controlled by `retry_jitter`.

data/lib/logister/client.rb

@@ -32,9 +32,13 @@ module Logister
       @queue         = SizedQueue.new(@configuration.queue_size)
       @worker        = nil
       @running       = false
+      @stopping      = false
       @pending_mutex = Mutex.new
       @pending_condition = ConditionVariable.new
       @pending_count = 0
+      @delivery_mutex = Mutex.new
+      @delivery_counts = { queued_events: 0, acknowledged_events: 0, unconfirmed_events: 0,
+                           queue_full_events: 0, retry_attempts: 0 }
 
       # Cache values that are static for the lifetime of this client so we
       # don't allocate on every send_request call.
@@ -48,6 +52,7 @@ module Logister
     end
 
     def publish(payload)
+      return false if ReportingScope.suppressed?
       return false unless ready?
 
       payload = with_stable_uuid(payload)
@@ -83,25 +88,40 @@ module Logister
     def shutdown
       return true unless @configuration.async
 
-      @running = false
-      begin
-        @queue.push(nil)
-      rescue StandardError
-        nil
+      worker = @worker_mutex.synchronize do
+        @stopping = true
+        begin
+          @queue.push(nil, true)
+        rescue ThreadError
+          # A full queue will be drained by the worker, which also checks the
+          # stopping flag. Never block the caller waiting to enqueue a sentinel.
+        end
+        @worker
       end
-      @worker&.join(1)
-      @worker = nil
-      true
+      worker&.join(1)
+      !worker&.alive?
+    end
+
+    # Process-local counters, never an assertion of exactly-once server receipt.
+    def delivery_stats
+      @delivery_mutex.synchronize { @delivery_counts.dup }
+        .merge(pending_events: @pending_mutex.synchronize { @pending_count })
     end
 
     private
 
     def enqueue(payload)
-      increment_pending
-      @queue.push(payload, true)
+      @worker_mutex.synchronize do
+        return false if @stopping
+
+        increment_pending
+        @queue.push(payload, true)
+      end
+      record_delivery(:queued_events, 1)
       true
     rescue ThreadError
       complete_pending(1)
+      record_delivery(:queue_full_events, 1, reason: 'queue_full')
       @configuration.logger.warn('logister queue full; dropping event')
       false
     end
@@ -111,6 +131,7 @@ module Logister
       return if @running && @worker&.alive?
 
       @worker_mutex.synchronize do
+        return if @stopping
         return if @running && @worker&.alive?
 
         @running = true
@@ -144,7 +165,7 @@ module Logister
 
         publish_batch_sync(batch)
         complete_pending(batch.length)
-        break if stop_after_batch
+        break if stop_after_batch || (@stopping && @queue.empty?)
       end
     rescue StandardError => e
       @configuration.logger.warn("logister worker crashed: #{e.class} #{e.message}")
@@ -158,14 +179,22 @@ module Logister
       attempts = 0
       begin
         attempts += 1
-        send_request(payload)
+        delivered = send_request(payload)
+        unless delivered
+          record_delivery(:unconfirmed_events, 1, reason: 'no_acknowledgment')
+          return false
+        end
+        record_delivery(:acknowledged_events, 1)
+        true
       rescue StandardError => e
         if attempts <= @configuration.max_retries && retryable_error?(e)
+          record_delivery(:retry_attempts, 1, reason: failure_reason(e))
           sleep(retry_delay(e, attempts))
           retry
         end
 
-        @configuration.logger.warn("logister publish failed: #{e.class} #{e.message}")
+        record_delivery(:unconfirmed_events, 1, reason: failure_reason(e))
+        @configuration.logger.warn("logister publish failed: #{e.class}")
         false
       end
     end
@@ -174,7 +203,13 @@ module Logister
       attempts = 0
       begin
         attempts += 1
-        send_batch_request(payloads)
+        delivered = send_batch_request(payloads)
+        unless delivered
+          record_delivery(:unconfirmed_events, payloads.length, reason: 'no_acknowledgment')
+          return false
+        end
+        record_delivery(:acknowledged_events, payloads.length)
+        true
       rescue UnsupportedBatchEndpoint
         payloads.map { |payload| publish_sync(payload) }.all?
       rescue RequestError => e
@@ -185,19 +220,23 @@ module Logister
           return first_half_delivered && second_half_delivered
         end
         if attempts <= @configuration.max_retries && retryable_error?(e)
+          record_delivery(:retry_attempts, 1, reason: failure_reason(e))
           sleep(retry_delay(e, attempts))
           retry
         end
 
-        @configuration.logger.warn("logister batch publish failed: #{e.class} #{e.message}")
+        record_delivery(:unconfirmed_events, payloads.length, reason: failure_reason(e))
+        @configuration.logger.warn("logister batch publish failed: #{e.class}")
         false
       rescue StandardError => e
         if attempts <= @configuration.max_retries && retryable_error?(e)
+          record_delivery(:retry_attempts, 1, reason: failure_reason(e))
           sleep(retry_delay(e, attempts))
           retry
         end
 
-        @configuration.logger.warn("logister batch publish failed: #{e.class} #{e.message}")
+        record_delivery(:unconfirmed_events, payloads.length, reason: failure_reason(e))
+        @configuration.logger.warn("logister batch publish failed: #{e.class}")
         false
       end
     end
@@ -290,6 +329,26 @@ module Logister
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    def failure_reason(error)
+      return "http_#{error.status}" if error.is_a?(RequestError)
+      return 'timeout' if error.is_a?(Timeout::Error)
+
+      'transport_error'
+    end
+
+    def record_delivery(counter, count, reason: nil)
+      @delivery_mutex.synchronize { @delivery_counts[counter] += count }
+      observer = @configuration.delivery_observer
+      return unless observer
+
+      ReportingScope.suppress do
+        observer.call({ outcome: counter.to_s, count: count, reason: reason }.compact.freeze)
+      end
+    rescue StandardError
+      # Counters survive observer failure; never report this through telemetry.
+      nil
+    end
+
     def with_stable_uuid(payload)
       attributes = payload.to_h.dup
       key = attributes.keys.any? { |candidate| candidate.is_a?(String) } ? 'uuid' : :uuid

data/lib/logister/configuration.rb

@@ -10,7 +10,7 @@ module Logister
                   :capture_db_metrics, :db_metric_min_duration_ms, :db_metric_sample_rate,
                   :feature_flags_resolver, :dependency_resolver, :anonymize_ip,
                   :max_breadcrumbs, :max_dependencies, :capture_request_spans,
-                  :capture_sql_breadcrumbs, :sql_breadcrumb_min_duration_ms
+                  :capture_sql_breadcrumbs, :sql_breadcrumb_min_duration_ms, :delivery_observer
     attr_writer :deployment_endpoint, :batch_endpoint
 
     def initialize
@@ -32,6 +32,7 @@ module Logister
       @ignore_environments = []
       @ignore_paths = []
       @before_notify = nil
+      @delivery_observer = nil
 
       @async = true
       @queue_size = 1000

data/lib/logister/reporter.rb

@@ -298,6 +298,10 @@ module Logister
       @client.flush(timeout: timeout)
     end
 
+    def delivery_stats
+      @client.delivery_stats
+    end
+
     def shutdown
       @client.shutdown
     end

data/lib/logister/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Logister
-  VERSION = '0.4.1'
+  VERSION = '0.4.2'
 end

data/lib/logister.rb

@@ -64,6 +64,10 @@ module Logister
       reporter.flush(timeout: timeout)
     end
 
+    def delivery_stats
+      reporter.delivery_stats
+    end
+
     def shutdown
       reporter.shutdown
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: logister-ruby
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Logister
 bindir: bin
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport