forge_ops_tracker 0.7.0 → 0.10.1

data/lib/forge_ops_tracker/span_buffer.rb

@@ -0,0 +1,65 @@
+require "securerandom"
+
+module ForgeOpsTracker
+  # Accumulates one request's own nested call tree in-process; the tracing analog to
+  # BreadcrumbBuffer's per-thread trail. ForgeOpsTracker::Middleware::SpanTracing resets this to a
+  # fresh buffer at the start of every request, with a freshly generated trace_id and root
+  # span_id, and reads it back once the request is over to decide whether this trace is worth
+  # sending at all (see that middleware's own comment for exactly where and why).
+  #
+  # The stack exists so nesting can be reconstructed correctly even though most of what's recorded
+  # here (a query, an outbound HTTP call, a Redis call) only has a start+duration known *after* the
+  # fact, not a real "this span is now open" moment the way a manually-wrapped ForgeOpsTracker.span
+  # block has. Whatever's on top of the stack at the moment a leaf span is recorded is that leaf's
+  # real parent: the nearest currently-open span, whether that's the request's own root, or a
+  # service-level span a customer wrapped their own code in. The root span_id is pushed onto the
+  # stack immediately, at construction, specifically so every span recorded before the controller
+  # action itself finishes (which is every one of them, since process_action.action_controller's
+  # own subscription only fires once the whole action, including everything nested inside it, has
+  # already run) naturally nests under it without the root having to exist as a real recorded span
+  # first.
+  class SpanBuffer
+    attr_reader :trace_id, :root_span_id, :spans
+
+    def initialize
+      @trace_id = SecureRandom.hex(16)
+      @root_span_id = SecureRandom.hex(8)
+      @spans = []
+      @stack = [ @root_span_id ]
+      @root_duration_ms = nil
+    end
+
+    def current_parent_id
+      @stack.last
+    end
+
+    def push(span_id)
+      @stack.push(span_id)
+    end
+
+    def pop
+      @stack.pop
+    end
+
+    # root: true only for the one call that records the request's own root span (see Railtie's
+    # process_action.action_controller subscription): forces parent_span_id nil explicitly, since
+    # by the time that fires, the root's own span_id has already been popped off the stack (there's
+    # nothing left on it to read back as "the parent" at that point - correctly, since the root has
+    # no parent of its own).
+    def record(span_id:, name:, kind:, started_at:, duration_ms:, data: {}, root: false)
+      parent_span_id = root ? nil : current_parent_id
+      spans << {
+        span_id: span_id, parent_span_id: parent_span_id, name: name, kind: kind,
+        started_at: started_at.utc.iso8601(3), duration_ms: duration_ms, data: data
+      }
+      @root_duration_ms = duration_ms if root
+    end
+
+    # nil (never sent) until the root span has actually been recorded; a request that somehow never
+    # fires process_action.action_controller at all (a request Rails itself never routes) has no
+    # duration to compare against a threshold, so it's never mistakenly treated as "slow."
+    def slow?(threshold_ms)
+      @root_duration_ms && @root_duration_ms >= threshold_ms
+    end
+  end
+end

data/lib/forge_ops_tracker/span_queue.rb

@@ -0,0 +1,61 @@
+require "thread"
+
+module ForgeOpsTracker
+  # Same shape and reasoning as DeliveryQueue: a small in-process background thread + bounded
+  # queue, so delivering a captured trace never adds latency to the very request it was just
+  # measuring - the one thing that would be actively counterproductive here, blocking an already-
+  # slow request even longer just to report that it was slow. One whole trace (a trace_id plus
+  # every span belonging to it) is one queue entry, delivered as one client call, not batched
+  # together with other traces the way PerformanceFlusher/FailureEventBuffer batch over a time
+  # window: a trace is already a complete, immediately-relevant unit the moment a request
+  # finishes, so it's delivered promptly rather than held for up to a full flush interval.
+  class SpanQueue
+    def initialize(configuration, client: Client.new(configuration))
+      @configuration = configuration
+      @client = client
+      @queue = SizedQueue.new(configuration.queue_size)
+      @mutex = Mutex.new
+      @thread = nil
+    end
+
+    # Dropping a whole trace silently (never blocking the caller) if the queue is already full,
+    # the same backpressure-must-never-reach-the-host-app posture DeliveryQueue#push already
+    # documents; a burst of several slow requests at once must never stall a request that's
+    # already been identified as slow even further.
+    def push(trace_id:, spans:)
+      ensure_worker_started
+      @queue.push({ trace_id: trace_id, spans: spans }, true)
+      true
+    rescue ThreadError
+      log { "span delivery queue full, dropping trace" }
+      false
+    end
+
+    private
+      attr_reader :configuration, :client
+
+      def ensure_worker_started
+        return if @thread&.alive?
+
+        @mutex.synchronize do
+          return if @thread&.alive?
+
+          @thread = Thread.new { run }
+          @thread.abort_on_exception = false
+        end
+      end
+
+      def run
+        loop do
+          entry = @queue.pop
+          client.deliver_spans(trace_id: entry[:trace_id], spans: entry[:spans])
+        rescue StandardError => e
+          log { "span delivery thread error: #{e.class}: #{e.message}" }
+        end
+      end
+
+      def log
+        configuration.logger&.debug { "[ForgeOpsTracker] #{yield}" }
+      end
+  end
+end

data/lib/forge_ops_tracker/version.rb

@@ -1,3 +1,3 @@
 module ForgeOpsTracker
-  VERSION = "0.7.0"
+  VERSION = "0.10.1"
 end

data/lib/forge_ops_tracker.rb

@@ -1,3 +1,4 @@
+require "securerandom"
 require "forge_ops_tracker/version"
 require "forge_ops_tracker/configuration"
 require "forge_ops_tracker/pii_scrubber"
@@ -6,13 +7,20 @@ require "forge_ops_tracker/client"
 require "forge_ops_tracker/delivery_queue"
 require "forge_ops_tracker/error_subscriber"
 require "forge_ops_tracker/session_flusher"
+require "forge_ops_tracker/histogram_bucketer"
 require "forge_ops_tracker/performance_flusher"
 require "forge_ops_tracker/performance_instrumentation"
 require "forge_ops_tracker/metric_buffer"
 require "forge_ops_tracker/infrastructure_metric_buffer"
+require "forge_ops_tracker/failure_event_buffer"
 require "forge_ops_tracker/periodic_poller"
+require "forge_ops_tracker/breadcrumb_buffer"
+require "forge_ops_tracker/span_buffer"
+require "forge_ops_tracker/span_queue"
 require "forge_ops_tracker/middleware/session_tracking"
 require "forge_ops_tracker/middleware/user_context"
+require "forge_ops_tracker/middleware/breadcrumb_context"
+require "forge_ops_tracker/middleware/span_tracing"
 
 module ForgeOpsTracker
   class << self
@@ -59,6 +67,54 @@ module ForgeOpsTracker
       Thread.current[:forge_ops_tracker_current_user] = user.empty? ? nil : user
     end
 
+    # Adds one breadcrumb to the current request's trail (or, outside a request entirely, a
+    # background job or console session's own trail for the rest of this thread: see
+    # ForgeOpsTracker::Middleware::BreadcrumbContext for how a request gets its own buffer to start
+    # with). Lazily creates a buffer on this thread if BreadcrumbContext never ran (Sidekiq/Solid
+    # Queue jobs don't go through Rack middleware at all, an IRB/rails console session even less
+    # so), the same "works standalone, no specific setup required" shape ForgeOpsTracker.set_user
+    # already has. Works whether or not track_breadcrumbs is on: that flag only gates the automatic
+    # sql.active_record/process_action.action_controller/Net::HTTP sources Railtie installs, never
+    # this manual call.
+    def add_breadcrumb(message, category: "custom", level: "info", data: {})
+      buffer = (Thread.current[:forge_ops_tracker_breadcrumbs] ||= BreadcrumbBuffer.new(configuration))
+      buffer.add(category: category, message: message, level: level, data: data)
+    end
+
+    # Wraps a customer's own service-level code as one named, nested span in the current request's
+    # trace (e.g. `ForgeOpsTracker.span("PaymentService#charge") { ... }`), so its database/Redis/
+    # outbound-HTTP calls show up nested underneath it in the waterfall rather than appearing to
+    # hang directly off the controller root - there's no automatic way to detect "this is a
+    # logically distinct service layer" the way a SQL query or an HTTP request already has a real
+    # instrumentation hook to detect, so this is deliberately explicit, opt-in, by hand, unlike
+    # every other span kind this gem records automatically.
+    #
+    # A plain pass-through (still runs the block, records nothing) with no error and no special
+    # handling whenever there's no current request trace to nest under at all: outside a request
+    # entirely (a background job, a console session), when track_tracing is off, or when the gem
+    # isn't enabled - the same "never break the host app's own code path" posture every other
+    # capture method in this gem already takes. Unlike add_breadcrumb, this does NOT lazily create
+    # a standalone buffer for itself: a lone span with no request-level trace around it, and no
+    # middleware left running to ever flush it, would just accumulate in this thread's memory
+    # forever with nothing to ever send it, which is worse than never recording it at all.
+    def span(name, kind: "service", data: {})
+      return yield unless configuration.enabled? && configuration.track_tracing
+
+      buffer = Thread.current[:forge_ops_tracker_spans]
+      return yield unless buffer
+
+      span_id = SecureRandom.hex(8)
+      started_at = Time.now.utc
+      buffer.push(span_id)
+      begin
+        yield
+      ensure
+        buffer.pop
+        duration_ms = (Time.now.utc - started_at) * 1000.0
+        buffer.record(span_id: span_id, name: name, kind: kind, started_at: started_at, duration_ms: duration_ms, data: data)
+      end
+    end
+
     private
       def metric_buffer
         @metric_buffer ||= MetricBuffer.new(configuration)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forge_ops_tracker
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.10.1
 platform: ruby
 authors:
 - ForgeOps
@@ -65,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: redis-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.30'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.30'
 description: Hooks Rails' error reporter and reports exceptions to a ForgeOps exception
   tracker instance over HTTP, without ever raising back into the host application.
 executables: []
@@ -75,18 +89,25 @@ files:
 - LICENSE.txt
 - README.md
 - lib/forge_ops_tracker.rb
+- lib/forge_ops_tracker/breadcrumb_buffer.rb
 - lib/forge_ops_tracker/client.rb
 - lib/forge_ops_tracker/configuration.rb
 - lib/forge_ops_tracker/delivery_queue.rb
 - lib/forge_ops_tracker/error_subscriber.rb
 - lib/forge_ops_tracker/event_builder.rb
+- lib/forge_ops_tracker/failure_event_buffer.rb
+- lib/forge_ops_tracker/histogram_bucketer.rb
 - lib/forge_ops_tracker/infrastructure_metric_buffer.rb
+- lib/forge_ops_tracker/integrations/active_record_pool.rb
 - lib/forge_ops_tracker/integrations/net_http.rb
 - lib/forge_ops_tracker/integrations/puma.rb
+- lib/forge_ops_tracker/integrations/redis_client.rb
 - lib/forge_ops_tracker/integrations/sidekiq.rb
 - lib/forge_ops_tracker/integrations/solid_queue.rb
 - lib/forge_ops_tracker/metric_buffer.rb
+- lib/forge_ops_tracker/middleware/breadcrumb_context.rb
 - lib/forge_ops_tracker/middleware/session_tracking.rb
+- lib/forge_ops_tracker/middleware/span_tracing.rb
 - lib/forge_ops_tracker/middleware/user_context.rb
 - lib/forge_ops_tracker/performance_flusher.rb
 - lib/forge_ops_tracker/performance_instrumentation.rb
@@ -94,6 +115,8 @@ files:
 - lib/forge_ops_tracker/pii_scrubber.rb
 - lib/forge_ops_tracker/railtie.rb
 - lib/forge_ops_tracker/session_flusher.rb
+- lib/forge_ops_tracker/span_buffer.rb
+- lib/forge_ops_tracker/span_queue.rb
 - lib/forge_ops_tracker/version.rb
 homepage: https://getforgeops.net
 licenses: