forge_ops_tracker 0.5.0 → 0.10.1

data/lib/forge_ops_tracker/railtie.rb

@@ -2,6 +2,34 @@ require "rails/railtie"
 
 module ForgeOpsTracker
   class Railtie < ::Rails::Railtie
+    # Shared across every performance-timing subscription/integration below (controller, query,
+    # job, raw Sidekiq, outbound Net::HTTP): one flusher, one background thread, one set of
+    # buckets, since PerformanceFlusher already buckets on [transaction_name, kind] and safely
+    # handles concurrent calls from several sources at once. Exposed as a class method, not a
+    # local variable inside one initializer, specifically so the Sidekiq/Net::HTTP integrations
+    # (each guarded by their own separate initializer, since each only loads if its own optional
+    # library is present) can record into the exact same instance rather than each starting a
+    # redundant flusher/thread of their own.
+    class << self
+      def performance_flusher
+        @performance_flusher ||= ForgeOpsTracker::PerformanceFlusher.new(ForgeOpsTracker.configuration)
+      end
+
+      # Same reasoning as performance_flusher above, exposed the identical way: shared across the
+      # two failure-detecting call sites below (the perform.active_job subscription, Net::HTTP's
+      # own Timing#request), one buffer/thread rather than each starting a redundant one.
+      def failure_event_buffer
+        @failure_event_buffer ||= ForgeOpsTracker::FailureEventBuffer.new(ForgeOpsTracker.configuration)
+      end
+
+      # Same reasoning again, exposed the identical way: shared across every call site that might
+      # finish a captured trace (Middleware::SpanTracing today; nothing else yet, but the same
+      # "one instance, not one per call site" reasoning applies regardless).
+      def span_queue
+        @span_queue ||= ForgeOpsTracker::SpanQueue.new(ForgeOpsTracker.configuration)
+      end
+    end
+
     initializer "forge_ops_tracker.subscribe_error_reporter" do |app|
       configuration = ForgeOpsTracker.configuration
       configuration.app_root ||= app.root.to_s
@@ -14,5 +42,249 @@ module ForgeOpsTracker
     initializer "forge_ops_tracker.track_sessions" do |app|
       app.middleware.use ForgeOpsTracker::Middleware::SessionTracking, configuration: ForgeOpsTracker.configuration
     end
+
+    # Warden::Manager (mounted automatically by Devise, or directly by any other Warden-based
+    # auth setup) sets env["warden"] itself; this only ever reads it, so it works regardless of
+    # exactly where in the middleware stack this ends up relative to Warden::Manager, as long as
+    # that key exists in env by the time this middleware's own #call runs, which is true for any
+    # Warden-based auth setup: it mounts its own middleware once, for the whole app, long before
+    # any individual request begins.
+    initializer "forge_ops_tracker.track_current_user" do |app|
+      app.middleware.use ForgeOpsTracker::Middleware::UserContext, configuration: ForgeOpsTracker.configuration
+    end
+
+    # Gives every request its own fresh BreadcrumbBuffer to accumulate into (see
+    # ForgeOpsTracker::Middleware::BreadcrumbContext for why this has to be a middleware, the same
+    # "Rails.error.subscribe never receives the Rack env" reasoning UserContext's own comment
+    # gives): must run before the sql.active_record/process_action.action_controller subscriptions
+    # below can have anywhere to record into, but Rack middleware ordering guarantees that already,
+    # since this wraps app.call(env), and those notifications only ever fire from *inside* that
+    # call.
+    initializer "forge_ops_tracker.track_breadcrumbs" do |app|
+      app.middleware.use ForgeOpsTracker::Middleware::BreadcrumbContext, configuration: ForgeOpsTracker.configuration
+    end
+
+    # Same "must run before the notifications below have anywhere to record into" reasoning as
+    # track_breadcrumbs's own comment just above, for the exact same structural reason (Rack
+    # middleware always wraps the actual controller dispatch those notifications fire from inside
+    # of, regardless of this initializer's own position relative to track_breadcrumbs/
+    # track_current_user/track_sessions).
+    initializer "forge_ops_tracker.track_tracing" do |app|
+      app.middleware.use ForgeOpsTracker::Middleware::SpanTracing, configuration: ForgeOpsTracker.configuration
+    end
+
+    # Rails already fires "process_action.action_controller" after every request with the
+    # controller/action and how long it took (event.duration, in ms) built in, so unlike session
+    # tracking above (which needed a Rack middleware because there's no single existing hook for
+    # "a request finished"), this needs no middleware of its own at all, just a subscriber.
+    # Guarded the same way the error subscriber and session-tracking middleware both are: on by
+    # default, off entirely if track_performance is turned off or the gem itself isn't enabled
+    # (no DSN configured, or the current environment isn't in enabled_environments).
+    #
+    # sql.active_record/perform.active_job are subscribed here too, not in their own separate
+    # initializers: all three (plus Sidekiq/Net::HTTP below) are genuinely the same concern
+    # (automatic performance timing), sharing the one performance_flusher above; see
+    # PerformanceInstrumentation for the actual transaction_name/skip decisions each one makes,
+    # kept out of these blocks specifically so that decision logic is unit-testable without a real
+    # Rails/ActiveJob boot (this gem's own test suite doesn't require Rails at all; see that
+    # file's own comment).
+    #
+    # The same two subscriptions also record a breadcrumb, gated on track_breadcrumbs
+    # independently of track_performance: an app could want the trail without the timing data, or
+    # vice versa, and each already has to check its own flag regardless, so there's no real cost
+    # to keeping them independent rather than tying breadcrumbs to whether performance monitoring
+    # happens to be on.
+    #
+    # Every event.time below is wrapped in Time.at(...) before being handed to SpanBuffer#record or
+    # job_queue_wait_ms, both of which need a real Time. ActiveSupport::Notifications::Event#time
+    # returns a plain Float (seconds since the epoch) on the Rails version this gem currently
+    # targets, not a Time; Time.at(...) also passes a real Time straight through unchanged, so this
+    # stays correct if a future Rails version goes back to returning one.
+    initializer "forge_ops_tracker.track_performance" do
+      configuration = ForgeOpsTracker.configuration
+      flusher = Railtie.performance_flusher
+
+      ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+        next unless configuration.enabled?
+
+        event = ActiveSupport::Notifications::Event.new(*args)
+        transaction_name = PerformanceInstrumentation.controller_transaction_name(event.payload)
+
+        if configuration.track_performance
+          flusher.record(transaction_name: transaction_name, duration_ms: event.duration, kind: "controller")
+        end
+
+        if configuration.track_breadcrumbs
+          status = event.payload[:status]
+          ForgeOpsTracker.add_breadcrumb(
+            "#{event.payload[:method]} #{transaction_name}",
+            category: "controller",
+            level: status && status >= 500 ? "error" : "info",
+            data: { status: status, path: event.payload[:path] }.compact
+          )
+        end
+
+        # Records this request's own root span, not gated on track_performance/track_breadcrumbs
+        # above (its own independent configuration.track_tracing flag instead, the same "several
+        # genuinely independent mechanisms recorded from the same instrumentation point" pattern
+        # this exact call site already established for breadcrumbs): this is the one call in the
+        # whole gem that ever passes root: true, since process_action.action_controller is the only
+        # instrumentation point that wraps a genuinely whole request. See SpanBuffer#record's own
+        # comment for why root: true has to force parent_span_id nil explicitly here rather than
+        # reading it off the (already-popped-by-now) stack.
+        if configuration.track_tracing && (buffer = Thread.current[:forge_ops_tracker_spans])
+          buffer.pop
+          buffer.record(
+            span_id: buffer.root_span_id, name: transaction_name, kind: "controller",
+            started_at: Time.at(event.time), duration_ms: event.duration, root: true
+          )
+        end
+      end
+
+      ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+        next unless configuration.enabled?
+
+        event = ActiveSupport::Notifications::Event.new(*args)
+        transaction_name = PerformanceInstrumentation.query_transaction_name(event.payload)
+        next if transaction_name.nil? # SCHEMA/cached, see PerformanceInstrumentation's own comment
+
+        if configuration.track_performance
+          flusher.record(transaction_name: transaction_name, duration_ms: event.duration, kind: "query")
+        end
+
+        if configuration.track_breadcrumbs
+          ForgeOpsTracker.add_breadcrumb(transaction_name, category: "query", data: { duration_ms: event.duration.round(1) })
+        end
+
+        # A leaf span, parented onto whatever's currently open (the controller root, or a
+        # manually-wrapped ForgeOpsTracker.span block around it): a query has no children of its
+        # own to nest anything under, so unlike the controller root above, this never touches the
+        # stack itself, just records against whatever's already on top of it.
+        if configuration.track_tracing && (buffer = Thread.current[:forge_ops_tracker_spans])
+          buffer.record(
+            span_id: SecureRandom.hex(8), name: transaction_name, kind: "database",
+            started_at: Time.at(event.time), duration_ms: event.duration
+          )
+        end
+      end
+
+      ActiveSupport::Notifications.subscribe("perform.active_job") do |*args|
+        # Permissive enough for either concern below to run on its own: track_performance off but
+        # track_failures on (or vice versa) still needs this subscription to fire at all.
+        next unless (configuration.track_performance || configuration.track_failures) && configuration.enabled?
+
+        event = ActiveSupport::Notifications::Event.new(*args)
+
+        if configuration.track_performance
+          transaction_name = PerformanceInstrumentation.job_transaction_name(event.payload)
+          flusher.record(transaction_name: transaction_name, duration_ms: event.duration, kind: "job")
+
+          # A second, independent sample from the same notification: how long this job actually
+          # waited in its queue before this perform even started, not how long perform itself took
+          # (the "job" kind above). Grouped by queue name, not job class, since queue-level backlog
+          # is the actionable unit here (a slow queue affects every job class routed through it),
+          # the same reason Solid Queue's own StatsReporter already reports queue_depth per queue
+          # name rather than per job class. See PerformanceInstrumentation.job_queue_wait_ms's own
+          # comment for why this is nil, and skipped, for a job that was never actually enqueued.
+          wait_ms = PerformanceInstrumentation.job_queue_wait_ms(event.payload, at: Time.at(event.time))
+          if wait_ms
+            flusher.record(transaction_name: event.payload[:job].queue_name, duration_ms: wait_ms, kind: "job_latency")
+          end
+        end
+
+        # Independent of track_performance above, same reasoning breadcrumbs already established
+        # at this exact call site: a job whose perform raised, via
+        # PerformanceInstrumentation.job_failure_details' own use of ActiveSupport::Notifications'
+        # automatic payload[:exception_object] (see that method's own comment).
+        if configuration.track_failures
+          failure = PerformanceInstrumentation.job_failure_details(event.payload)
+          if failure
+            Railtie.failure_event_buffer.record(
+              kind: "job", transaction_name: PerformanceInstrumentation.job_transaction_name(event.payload),
+              error_class: failure[:error_class], error_message: failure[:error_message]
+            )
+          end
+        end
+      end
+    end
+
+    # Raw (non-ActiveJob) Sidekiq::Worker job timing, plus Sidekiq's own queue-depth/processed/
+    # failed/etc. gauges: a separate initializer, since unlike ActiveRecord/ActionController
+    # (always present in any Rails app this gem's own gemspec already implies), Sidekiq is
+    # genuinely optional and isn't a declared dependency of this gem at all.
+    initializer "forge_ops_tracker.track_sidekiq" do
+      next unless defined?(::Sidekiq)
+
+      require "forge_ops_tracker/integrations/sidekiq"
+
+      configuration = ForgeOpsTracker.configuration
+      ::Sidekiq.configure_server do |config|
+        config.server_middleware do |chain|
+          # No extra args to chain.add: Sidekiq calls Middleware.new(*args) itself for every job,
+          # splatting whatever was passed here; the middleware's own keyword-argument defaults
+          # (ForgeOpsTracker.configuration, Railtie.performance_flusher) already resolve correctly
+          # when called with none, and passing a keyword hash through *args here is genuinely
+          # ambiguous (Sidekiq's own chain.add doc example passes a literal positional Hash, not
+          # keyword syntax, for exactly this reason).
+          chain.add ForgeOpsTracker::Integrations::Sidekiq::Middleware
+        end
+      end
+
+      ForgeOpsTracker::Integrations::Sidekiq::StatsReporter.start(configuration: configuration)
+    end
+
+    initializer "forge_ops_tracker.track_solid_queue" do
+      next unless defined?(::SolidQueue)
+
+      require "forge_ops_tracker/integrations/solid_queue"
+      ForgeOpsTracker::Integrations::SolidQueue::StatsReporter.start(configuration: ForgeOpsTracker.configuration)
+    end
+
+    initializer "forge_ops_tracker.track_puma" do
+      next unless defined?(::Puma)
+
+      require "forge_ops_tracker/integrations/puma"
+      ForgeOpsTracker::Integrations::Puma::StatsReporter.start(configuration: ForgeOpsTracker.configuration)
+    end
+
+    # Same defined? guard as track_sidekiq/track_solid_queue/track_puma above, not
+    # track_net_http's unconditional one: ActiveRecord is neither Ruby stdlib nor a declared
+    # dependency of this gem itself (this gem has none at all beyond Rails::Railtie being
+    # defined; see the gemspec's own comment on why even Sidekiq/Puma are dev-only dependencies),
+    # so an API-only Rails app with ActiveRecord genuinely removed is a real, if uncommon, case to
+    # guard against rather than assume away.
+    initializer "forge_ops_tracker.track_active_record_pool" do
+      next unless defined?(::ActiveRecord::Base)
+
+      require "forge_ops_tracker/integrations/active_record_pool"
+      ForgeOpsTracker::Integrations::ActiveRecordPool::StatsReporter.start(configuration: ForgeOpsTracker.configuration)
+    end
+
+    # Net::HTTP is always present (Ruby's own standard library), so this always prepends; the
+    # actual on/off decision happens at call time inside Timing#request itself (checking
+    # configuration.track_performance/enabled? the same way the subscriptions above do), so
+    # toggling that flag after boot still takes effect immediately, the same as every other
+    # automatic instrumentation point in this gem.
+    initializer "forge_ops_tracker.track_net_http" do
+      require "forge_ops_tracker/integrations/net_http"
+      Net::HTTP.prepend(ForgeOpsTracker::Integrations::NetHTTP::Timing)
+    end
+
+    # defined?(::RedisClient) guarded, the same way track_sidekiq/track_solid_queue/track_puma
+    # above are: RedisClient is neither Ruby stdlib nor a declared dependency of this gem (see the
+    # gemspec's own comment on why even Sidekiq/Puma are dev-only dependencies), so a host app with
+    # no Redis at all is a real case to guard against, not assume away. Runs after Rails itself has
+    # finished booting (config.after_initialize, not a plain initializer like track_net_http
+    # above): unlike Net::HTTP (Ruby stdlib, always loaded), whether RedisClient is defined yet at
+    # plain initializer time depends on load order relative to whatever gem requires it (redis,
+    # sidekiq, ActiveJob's redis queue adapter, ...), which this gem has no control over; deferring
+    # the defined? check to after every railtie (including this app's own dependencies) has
+    # finished initializing avoids a load-order-dependent false negative.
+    config.after_initialize do
+      next unless defined?(::RedisClient)
+
+      require "forge_ops_tracker/integrations/redis_client"
+      ::RedisClient.prepend(ForgeOpsTracker::Integrations::RedisClientTiming)
+    end
   end
 end

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.5.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,7 +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
@@ -17,6 +31,98 @@ module ForgeOpsTracker
     def configure
       yield configuration
     end
+
+    # Records a named business metric (a signup, a payment, anything a customer wants to name),
+    # buffered and flushed periodically as a batch rather than one network call per capture (see
+    # MetricBuffer). value defaults to 1.0 so a bare counter-style call ("a signup happened")
+    # needs no argument; pass an explicit one for a metric with a real magnitude ("a $49 payment
+    # happened"). A no-op, same as every other capture path in this gem, when the gem isn't
+    # enabled (no DSN configured, or the current environment isn't in enabled_environments).
+    def capture_metric(name, value: 1.0)
+      return unless configuration.enabled?
+
+      metric_buffer.record(metric_name: name, value: value)
+    end
+
+    # Records one infrastructure reading (CPU/memory/disk, or anything else a customer's own
+    # script reads) from one of their own hosts. hostname defaults to Configuration#server_name
+    # (already derived from Socket.gethostname), so a script running on the box it's reporting
+    # about doesn't need to pass one explicitly. Same buffered-batch delivery and no-op-when-
+    # disabled contract as capture_metric above.
+    def capture_infrastructure_metric(name, value:, hostname: nil)
+      return unless configuration.enabled?
+
+      infrastructure_metric_buffer.record(metric_name: name, value: value, hostname: hostname || configuration.server_name)
+    end
+
+    # Manually attaches an affected user to whatever gets reported for the rest of this request
+    # (or, outside a request entirely, in a background job or a console session, for the rest of
+    # this thread). Sets the same thread-local ForgeOpsTracker::Middleware::UserContext's own
+    # Warden auto-detection uses, so this composes with it rather than being a second, separate
+    # mechanism: call this after that middleware ran to override its guess, or call it standalone
+    # in an app with no Warden at all. id/email/username are all independently optional; a call
+    # with none of them (or all nil) clears whatever was set.
+    def set_user(id: nil, email: nil, username: nil)
+      user = { id: id, email: email, username: username }.compact
+      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)
+      end
+
+      def infrastructure_metric_buffer
+        @infrastructure_metric_buffer ||= InfrastructureMetricBuffer.new(configuration)
+      end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forge_ops_tracker
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.10.1
 platform: ruby
 authors:
 - ForgeOps
@@ -23,6 +23,62 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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: []
@@ -33,15 +89,34 @@ 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
+- lib/forge_ops_tracker/periodic_poller.rb
 - 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: