logister-ruby 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 381dffab29b34b6beffe54e105fcf8dc5151f59bde1e44cfbba1749d21bff763
-  data.tar.gz: 5fe2ef7923ebeb4aa440d4aff35b246b2d407da0fe11dd26e26633e491105657
+  metadata.gz: a71c622e00652d3d7cc881b852987bb0c16ce383456e8c6f1aaacb4d195bbca1
+  data.tar.gz: 3ce350703b176ce69a72bc96a2a860f29d615a5132ee242c0a0b39fbdb1bb54d
 SHA512:
-  metadata.gz: a5380bdc6bc4c7b4c1e4cb9e2c0d9d4cc4825f87d3517b57c22db7e63fff519071e46e9ad3555d3035819f4e1a64819d26305a1646f18cb32c02977cff925da2
-  data.tar.gz: b3d7c3a5932f560be7ec3b1dc1a88a2319799e2b166e91d8a6d6084e8d6d7eaf262c047c5d7f9ba3e095d44dc857d1ed701605ced120a2253a168d3568cc5687
+  metadata.gz: e62e74979448480d5d383c08b0b53f0f3e39789aa4ee050d85debe6a9a5c4b922779a5866fe4d48632bc96f3346c8b69799b63d92f2bd5c4152e866037d16fe0
+  data.tar.gz: ae516f75badb5bc30013410e9c540fb8066a63edd2c637ae320d26dc01016e660178f83a0da8b456b0b0efedd850af34bd6d6703b9693cd16d4c4878cf35b36a

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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.

data/README.md

@@ -464,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/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',
@@ -357,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.2'
+  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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: logister-ruby
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Logister
 bindir: bin
 cert_chain: []
-date: 2026-09-16 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