logister-ruby 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b8f77ab291c0d9132dc6ea5d6f1711644d73a7892e9b7dbc4f5bb3cf418fd8f
-  data.tar.gz: 83af842795eebffcbfe29135091e89243dcd34f0e61968e8887dc75a027947f5
+  metadata.gz: a71c622e00652d3d7cc881b852987bb0c16ce383456e8c6f1aaacb4d195bbca1
+  data.tar.gz: 3ce350703b176ce69a72bc96a2a860f29d615a5132ee242c0a0b39fbdb1bb54d
 SHA512:
-  metadata.gz: 64bdd3ca1271f84c6495883ad5dac8ca829e29ef07a5dc79391848fa344fbcf39ac757650be7356611d16b285bc45ffa561ecbc804ca0c426a887ce6593f4f57
-  data.tar.gz: 464876a85252f86ec25e507fde1a38ace3c152596756da77c682ea81a5f872d0a69b86db38404a911c42a331d932506c4162a18df60c118b10dae940542f7d19
+  metadata.gz: e62e74979448480d5d383c08b0b53f0f3e39789aa4ee050d85debe6a9a5c4b922779a5866fe4d48632bc96f3346c8b69799b63d92f2bd5c4152e866037d16fe0
+  data.tar.gz: ae516f75badb5bc30013410e9c540fb8066a63edd2c637ae320d26dc01016e660178f83a0da8b456b0b0efedd850af34bd6d6703b9693cd16d4c4878cf35b36a

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.5.0 - 2026-09-24
+
+- Propagate W3C request context through Rack and Rails, including logs, errors, transactions, and server spans.
+- Add immutable request handles and exact-origin outbound header helpers; preserve incoming trace flags and isolate concurrent request scopes.
+
+## 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`.
@@ -446,3 +464,37 @@ package identity before creating the GitHub Release. Never move a consumed tag.
 Weekly CI audits/tests current dependencies and cannot trigger automatic publication.
 Dependabot groups compatible minor/patch updates; major toolchain migrations keep
 separate PRs. Pin Actions to full commits and retain supported runtime floors.
+
+## Request correlation (0.5.0+)
+
+The Rack/Rails integration accepts strict W3C version 00 `traceparent` headers,
+creates a local server span, and applies its identity to automatic and manual
+telemetry during the request. It preserves the incoming trace flags. Each request
+has its own scope, cleared even when the request raises.
+
+For an outbound call, retain a child handle and apply headers only to the intended
+origin. Disable automatic redirects, or regenerate and validate headers for every
+hop. Keep telemetry and token-issuer calls outside this instrumentation.
+
+```ruby
+trace = Logister.outbound_trace_context
+headers = trace.headers_for("https://api.example.test/orders", allowed_origins: ["https://api.example.test"])
+# Pass headers to your HTTP client with automatic redirects disabled.
+# When that request fails:
+Logister.report_error(StandardError.new("Order request failed"), context: trace.to_h)
+```
+
+`Logister.current_trace_context` returns the immutable active request handle.
+Background jobs require explicitly supplied context; there is no automatic queue
+propagation in this release.
+
+A linked-project lookup also requires Logister 3.7+, the instance flag
+`LOGISTER_CROSS_PROJECT_CORRELATIONS=true`, and explicit project/environment
+connections under Settings → Integrations → Connected projects. Enable related
+requests on both projects. A connection never grants project access.
+
+Use the returned request handle when reporting a handled HTTP failure later.
+Do not attach the most recent request to an unrelated crash or OS diagnostic.
+Configure each app's own `release` and `environment`; mobile and backend releases
+are independent. The backend shows exact identifier evidence and retention gaps.
+See the [request correlation guide](https://logister.org/docs/request-correlation/).

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/context_helpers.rb

@@ -12,7 +12,7 @@ module Logister
       {
         runtime: {
           rubyVersion: RUBY_VERSION,
-          railsVersion: defined?(Rails) ? Rails.version : nil,
+          railsVersion: defined?(Rails) && Rails.respond_to?(:version) ? Rails.version : nil,
           rackVersion: defined?(Rack) ? Rack.release : nil,
           platform: RUBY_PLATFORM
         }.compact
@@ -44,6 +44,9 @@ module Logister
     end
 
     def trace_context(headers:, env:)
+      current = Logister::ContextStore.trace_context
+      return current.to_h.merge(trace: {traceId: current.trace_id, spanId: current.span_id, requestId: current.request_id}) if current
+
       traceparent = header_value(headers, "Traceparent")
       b3_trace_id = header_value(headers, "X-B3-Traceid")
       b3_span_id = header_value(headers, "X-B3-Spanid")
@@ -196,15 +199,9 @@ module Logister
     def parse_traceparent(traceparent)
       return [ nil, nil, nil ] if traceparent.to_s.empty?
 
-      parts = traceparent.to_s.split("-")
-      return [ nil, nil, nil ] unless parts.size == 4
-
-      trace_id = parts[1].to_s
-      span_id = parts[2].to_s
-      flags = parts[3].to_s
-      sampled = flags.end_with?("01")
-
-      [ trace_id.presence, span_id.presence, sampled ]
+      parsed = Logister::TraceContext.parse(traceparent)
+      return [nil, nil, nil] unless parsed
+      [parsed[:trace_id], parsed[:parent_span_id], (parsed[:flags].to_i(16) & 1) == 1]
     rescue StandardError
       [ nil, nil, nil ]
     end

data/lib/logister/context_store.rb

@@ -25,6 +25,14 @@ module Logister
       trim_collection!(breadcrumbs, max_breadcrumbs)
     end
 
+    def trace_context
+      request_scope[:trace_context]
+    end
+
+    def trace_context=(value)
+      request_scope[:trace_context] = value
+    end
+
     def breadcrumbs
       request_scope[:breadcrumbs].dup
     end

data/lib/logister/middleware.rb

@@ -12,8 +12,14 @@ module Logister
 
     def call(env)
       Logister::ContextStore.reset_request_scope!
+      Logister::ContextStore.trace_context = Logister::TraceContext.from_headers(
+        traceparent: env["HTTP_TRACEPARENT"], request_id: env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
+      )
+      env["logister.trace_context"] = Logister::ContextStore.trace_context
       started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      @app.call(env)
+      status, headers, body = @app.call(env)
+      headers = headers.merge("x-request-id" => Logister::ContextStore.trace_context.request_id)
+      [status, headers, body]
     rescue StandardError => e
       request = ActionDispatch::Request.new(env)
       request_context = build_request_context(request, env, error: e, started_at: started_at)

data/lib/logister/reporter.rb

@@ -146,7 +146,10 @@ module Logister
 
       started_at ||= Time.now.utc - (duration_ms.to_f / 1000.0)
       span_id ||= SecureRandom.hex(8)
-      trace_id ||= span_id
+      active = Logister::ContextStore.trace_context
+      trace_id ||= active&.trace_id || SecureRandom.hex(16)
+      request_id ||= active&.request_id
+      parent_span_id ||= active&.span_id unless span_id == active&.span_id
 
       payload = build_payload(
         event_type: 'span',
@@ -298,6 +301,10 @@ module Logister
       @client.flush(timeout: timeout)
     end
 
+    def delivery_stats
+      @client.delivery_stats
+    end
+
     def shutdown
       @client.shutdown
     end
@@ -353,7 +360,7 @@ module Logister
         # Merge static config context last so caller-supplied keys are not
         # overwritten, then merge the static values. The static_context Hash
         # is frozen and reused — only the new outer Hash is allocated.
-        context:     @static_context.merge(context)
+        context:     @static_context.merge(Logister::ContextStore.trace_context&.to_h || {}).merge(context)
       }
     end
 

data/lib/logister/request_subscriber.rb

@@ -8,8 +8,8 @@ module Logister
       def install!
         return if @installed
 
-        ActiveSupport::Notifications.subscribe("process_action.action_controller") do |_name, _started, _finished, _id, payload|
-          handle_process_action(payload)
+        ActiveSupport::Notifications.subscribe("process_action.action_controller") do |_name, started, finished, _id, payload|
+          handle_process_action(payload.merge(duration: (finished - started) * 1000.0, started_at: started))
         end
 
         ActiveSupport::Notifications.subscribe("sql.active_record") do |_name, started, finished, _id, payload|
@@ -25,7 +25,7 @@ module Logister
         return if Logister.reporting_suppressed?
         return unless payload.is_a?(Hash)
 
-        request_id = payload[:request_id].to_s.presence
+        request_id = Logister::ContextStore.trace_context&.request_id || payload[:request_id].to_s.presence || payload[:request]&.request_id
         return unless request_id
 
         Logister::ContextStore.store_request_summary(
@@ -65,13 +65,16 @@ module Logister
         return unless duration_ms&.positive?
 
         route = "#{payload[:controller]}##{payload[:action]}"
-        started_at = Time.now.utc - (duration_ms / 1000.0)
+        started_at = payload[:started_at] || Time.now.utc - (duration_ms / 1000.0)
+        trace = Logister::ContextStore.trace_context || Logister::TraceContext.from_headers(request_id: request_id)
 
         Logister.report_span(
           name: route,
           kind: "server",
           status: payload[:status].to_i >= 500 ? "error" : "ok",
-          trace_id: request_id,
+          trace_id: trace.trace_id,
+          span_id: trace.span_id,
+          parent_span_id: trace.parent_span_id,
           request_id: request_id,
           duration_ms: duration_ms,
           started_at: started_at,

data/lib/logister/trace_context.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "uri"
+
+module Logister
+  # Immutable request identity. Capturing this value lets a caller report a failed
+  # request later without borrowing another concurrent request's identity.
+  class TraceContext
+    attr_reader :trace_id, :span_id, :parent_span_id, :request_id, :flags
+
+    def initialize(trace_id: SecureRandom.hex(16), span_id: SecureRandom.hex(8), parent_span_id: nil, request_id: SecureRandom.uuid, flags: "01")
+      @trace_id, @span_id, @parent_span_id, @request_id, @flags = [trace_id, span_id, parent_span_id, request_id, flags].map { |value| value&.dup&.freeze }
+      freeze
+    end
+
+    def self.parse(value)
+      match = /\A00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})\z/.match(value.to_s)
+      return unless match && match[1] != "0" * 32 && match[2] != "0" * 16
+      {trace_id: match[1], parent_span_id: match[2], flags: match[3]}
+    end
+
+    def self.from_headers(traceparent: nil, request_id: nil)
+      request_id = nil unless request_id.is_a?(String) && request_id.match?(/\A[A-Za-z0-9._:-]{1,200}\z/)
+      new(**(parse(traceparent) || {}), request_id: request_id || SecureRandom.uuid)
+    end
+
+    def to_h
+      {trace_id: trace_id, span_id: span_id, parent_span_id: parent_span_id, request_id: request_id}.compact
+    end
+
+    def child
+      self.class.new(trace_id: trace_id, parent_span_id: span_id, request_id: request_id, flags: flags)
+    end
+
+    def traceparent = "00-#{trace_id}-#{span_id}-#{flags}"
+
+    # Apply only to the exact destination origin. HTTP clients must call this on
+    # each redirect hop, or disable redirects; never forward the returned headers.
+    def headers_for(url, allowed_origins:)
+      return {} unless self.class.parse(traceparent) && request_id.is_a?(String) && request_id.match?(/\A[A-Za-z0-9._:-]{1,200}\z/)
+      origin = self.class.origin(url)
+      return {} unless origin && allowed_origins.any? { |allowed| self.class.origin(allowed) == origin }
+      {"traceparent" => traceparent, "x-request-id" => request_id}
+    end
+
+    def self.origin(url)
+      uri = URI.parse(url.to_s)
+      return unless %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo
+      [uri.scheme, uri.host.downcase, uri.port]
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+end

data/lib/logister/version.rb

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

data/lib/logister.rb

@@ -5,12 +5,23 @@ require_relative 'logister/client'
 require_relative 'logister/reporter'
 require_relative 'logister/context_helpers'
 require_relative 'logister/context_store'
+require_relative 'logister/trace_context'
 require_relative 'logister/middleware'
 require_relative 'logister/sql_subscriber'
 require_relative 'logister/request_subscriber'
 
 module Logister
   class << self
+    def current_trace_context
+      ContextStore.trace_context
+    end
+
+    # The returned child is the handle for this outbound attempt. Supply its
+    # to_h as context when reporting an error after the request scope has ended.
+    def outbound_trace_context
+      (current_trace_context || TraceContext.new).child
+    end
+
     def configuration
       @configuration ||= Configuration.new
     end
@@ -64,6 +75,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.5.0
 platform: ruby
 authors:
 - Logister
 bindir: bin
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -109,6 +109,7 @@ files:
 - lib/logister/reporting_scope.rb
 - lib/logister/request_subscriber.rb
 - lib/logister/sql_subscriber.rb
+- lib/logister/trace_context.rb
 - lib/logister/version.rb
 - logister-ruby.gemspec
 homepage: https://github.com/taimoorq/logister-ruby