dead_bro 0.2.29 → 0.2.30

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a338a291bd4ec9c69be1850484d683b67cca4bccd4efc29b73e8469130997cb
-  data.tar.gz: 9c77106ee1b182ebd76928929bca1ca143e9a06647fcb9f5cc4cf00b1c67490b
+  metadata.gz: cccae4ac857f38e889e12c292943b25fad11f7e372d7f13e4eb838d13c6330ee
+  data.tar.gz: 4d459c4d049219747ed5c1b6f10e1417648282eca2e3e81c7eeef132e8a347bd
 SHA512:
-  metadata.gz: 19af4bc9fc35ea4823a6a66fb20dd39e6fe41c778dd34a5b3d5d7109fac62b90170506f5c3d1359d864590b5e61fe61d3d8db79ca20be535bef80f7938801a2f
-  data.tar.gz: 30271ddbb549baf03d2acc8885dd45c19c49778893d427eeb79ef8e23b0b39467b5dbf65f6d47b84c2d555117ddf36929e604bdbde73171e46c27b9073ae36b9
+  metadata.gz: d12c33c0902c95f318cd716d7c88c78925543b235729ee90525d0453b16ed46521e2b00cc1daa5131b673abb7ee7e74e0968f299d56da055fd36452c2e314b90
+  data.tar.gz: e04ca78806e4d9a07757c0fedc177c2e4b77b295437d415fab94546d84add717ceab84791e34991f4955197ab1d8036ad498d679b089e795e5356beb0662d286

data/CHANGELOG.md

@@ -3,6 +3,11 @@
 ### Added
 - Monitor thread now sends a synchronous heartbeat on startup before the first collection tick. This ensures remote settings — including `monitor_enabled` — are applied from the very first reporting cycle, so Sidekiq workers and other non-web processes that have not yet sent any metrics still receive the correct configuration immediately on boot rather than waiting up to 60 seconds for the first scheduled tick.
 
+## [0.2.30] - 2026-06-19
+
+### Added
+- **`DeadBro.watch(label, **tags) { ... }`**: opt-in scoped timing for arbitrary code during instrumented web requests and background jobs. Records elapsed time, `start_offset_ms`, nesting depth, SQL count/duration attributable to the block, optional tags, and exception metadata (then re-raises). Spans are sent as `watch_events` in the normal APM payload for the Request Trace waterfall. Disabled by default; enable locally via `DeadBro.configure { |c| c.watch_enabled = true }` or remotely via the `watch_enabled` setting. Guardrails: max depth 10, max 50 spans per request, label length 200 chars, max 5 tags per span with tag values truncated to 100 chars. **Nested SQL:** each span diffs the request-wide SQL counter at enter/exit; parent spans include SQL from nested child spans (inclusive totals — use inner spans for per-block SQL, do not sum parent + child counts).
+
 ## [0.2.25] - 2026-06-14
 
 ### Added

data/lib/dead_bro/configuration.rb

@@ -17,7 +17,7 @@ module DeadBro
 
     # Remote-managed settings (overwritten by backend JSON `settings` on successful API responses)
     attr_accessor :memory_tracking_enabled, :allocation_tracking_enabled, :allocation_sample_rate,
-      :sample_rate, :slow_query_threshold_ms,
+      :sample_rate, :slow_query_threshold_ms, :watch_enabled,
       :monitor_enabled, :enable_db_stats, :enable_process_stats, :enable_system_stats,
       :max_sql_queries_to_send, :max_logs_to_send
 
@@ -67,7 +67,7 @@ module DeadBro
     REMOTE_SETTING_KEYS = %w[
       enabled sample_rate memory_tracking_enabled allocation_tracking_enabled allocation_sample_rate
       explain_analyze_enabled slow_query_threshold_ms max_sql_queries_to_send max_logs_to_send
-      excluded_controllers excluded_jobs exclusive_controllers exclusive_jobs
+      watch_enabled excluded_controllers excluded_jobs exclusive_controllers exclusive_jobs
       monitor_enabled enable_db_stats enable_process_stats enable_system_stats
       sample_rates_by_type
     ].freeze
@@ -102,6 +102,7 @@ module DeadBro
       @slow_query_threshold_ms = 500
       @max_sql_queries_to_send = 500
       @max_logs_to_send = 100
+      @watch_enabled = false
       self.excluded_controllers = []
       self.excluded_jobs = []
       self.exclusive_controllers = []
@@ -178,7 +179,7 @@ module DeadBro
             # must never be able to switch it on — only off. The local opt-in
             # (explain_analyze_enabled) stays untouched; see #explain_analyze_active?
             @remote_explain_analyze_enabled = !!value
-          when "enabled", "memory_tracking_enabled", "allocation_tracking_enabled",
+          when "enabled", "memory_tracking_enabled", "allocation_tracking_enabled", "watch_enabled",
                "monitor_enabled", "enable_db_stats", "enable_process_stats", "enable_system_stats"
             send(:"#{k}=", !!value)
           when "excluded_controllers", "excluded_jobs", "exclusive_controllers", "exclusive_jobs"
@@ -208,6 +209,10 @@ module DeadBro
       Time.now.utc < t
     end
 
+    def watch_enabled?
+      !!@watch_enabled
+    end
+
     def resolve_deploy_id
       explicit = @explicit_deploy_revision&.to_s&.strip
       return explicit unless explicit.nil? || explicit.empty?

data/lib/dead_bro/job_sql_tracking_middleware.rb

@@ -40,6 +40,8 @@ module DeadBro
         if defined?(DeadBro::DbConnectionSubscriber)
           DeadBro::DbConnectionSubscriber.start_request_tracking
         end
+
+        DeadBro::WatchTracker.start_request_tracking if defined?(DeadBro::WatchTracker)
       end
     rescue
       # Never raise from instrumentation install

data/lib/dead_bro/job_subscriber.rb

@@ -61,6 +61,7 @@ module DeadBro
           DeadBro::SqlSubscriber.start_request_tracking
           start_job_dependency_tracking
           DeadBro::DbConnectionSubscriber.start_request_tracking if defined?(DeadBro::DbConnectionSubscriber)
+          DeadBro::WatchTracker.start_request_tracking if defined?(DeadBro::WatchTracker)
           if DeadBro.configuration.allocation_tracking_enabled && defined?(DeadBro::MemoryTrackingSubscriber)
             DeadBro::MemoryTrackingSubscriber.start_request_tracking
           else
@@ -74,6 +75,7 @@ module DeadBro
         db_connection_stats = defined?(DeadBro::DbConnectionSubscriber) ? DeadBro::DbConnectionSubscriber.stop_request_tracking : {}
         gc_pressure = defined?(DeadBro::GcTracker) ? DeadBro::GcTracker.stop_request_tracking : {}
         ar_instantiation_count = defined?(DeadBro::ArObjectTracker) ? DeadBro::ArObjectTracker.stop_request_tracking : nil
+        watch_events = defined?(DeadBro::WatchTracker) ? DeadBro::WatchTracker.stop_request_tracking : []
 
         # Stop memory tracking and get collected memory data
         if DeadBro.configuration.allocation_tracking_enabled && defined?(DeadBro::MemoryTrackingSubscriber)
@@ -124,6 +126,7 @@ module DeadBro
           gc_stats: gc_stats,
           memory_events: memory_events,
           memory_performance: memory_performance,
+          watch_events: watch_events,
           logs: DeadBro.logger.logs
         }.merge(dependency_events)
 
@@ -162,6 +165,7 @@ module DeadBro
           DeadBro::SqlSubscriber.start_request_tracking
           start_job_dependency_tracking
           DeadBro::DbConnectionSubscriber.start_request_tracking if defined?(DeadBro::DbConnectionSubscriber)
+          DeadBro::WatchTracker.start_request_tracking if defined?(DeadBro::WatchTracker)
           if DeadBro.configuration.allocation_tracking_enabled && defined?(DeadBro::MemoryTrackingSubscriber)
             DeadBro::MemoryTrackingSubscriber.start_request_tracking
           else
@@ -175,6 +179,7 @@ module DeadBro
         db_connection_stats = defined?(DeadBro::DbConnectionSubscriber) ? DeadBro::DbConnectionSubscriber.stop_request_tracking : {}
         gc_pressure = defined?(DeadBro::GcTracker) ? DeadBro::GcTracker.stop_request_tracking : {}
         ar_instantiation_count = defined?(DeadBro::ArObjectTracker) ? DeadBro::ArObjectTracker.stop_request_tracking : nil
+        watch_events = defined?(DeadBro::WatchTracker) ? DeadBro::WatchTracker.stop_request_tracking : []
 
         # Stop memory tracking and get collected memory data
         if DeadBro.configuration.allocation_tracking_enabled && defined?(DeadBro::MemoryTrackingSubscriber)
@@ -228,6 +233,7 @@ module DeadBro
           gc_stats: gc_stats,
           memory_events: memory_events,
           memory_performance: memory_performance,
+          watch_events: watch_events,
           logs: DeadBro.logger.logs
         }.merge(dependency_events)
 
@@ -255,6 +261,7 @@ module DeadBro
       if DeadBro.configuration.allocation_tracking_enabled && defined?(DeadBro::MemoryTrackingSubscriber)
         DeadBro::MemoryTrackingSubscriber.stop_request_tracking
       end
+      DeadBro::WatchTracker.stop_request_tracking if defined?(DeadBro::WatchTracker)
     rescue
       # Best effort
     end

data/lib/dead_bro/sql_subscriber.rb

@@ -50,6 +50,21 @@ module DeadBro
       stack.last
     end
 
+    # Sum of SQL counts and durations recorded so far in the active tracking
+    # context. Used by WatchTracker to attribute SQL to a DeadBro.watch block.
+    def self.current_sql_metrics
+      agg_stack = Thread.current[THREAD_LOCAL_AGGREGATES_KEY]
+      aggregates_h = (agg_stack.is_a?(Array) && agg_stack.any?) ? agg_stack.last : {}
+      return {count: 0, duration_ms: 0.0} unless aggregates_h.is_a?(Hash) && aggregates_h.any?
+
+      {
+        count: aggregates_h.values.sum { |a| (a[:count] || 0).to_i },
+        duration_ms: aggregates_h.values.sum { |a| (a[:total_duration_ms] || 0.0).to_f }.round(2)
+      }
+    rescue StandardError
+      {count: 0, duration_ms: 0.0}
+    end
+
     # Check if we should continue tracking based on count and time limits
     def self.should_continue_tracking?(current_queries_array, max_count)
       return false unless current_queries_array.is_a?(Array)

data/lib/dead_bro/sql_tracking_middleware.rb

@@ -82,6 +82,9 @@ module DeadBro
       # Start CPU time tracking for this request (thread-local clock)
       DeadBro::CpuTracker.start_request_tracking if defined?(DeadBro::CpuTracker)
 
+      # Start user-defined watch block tracking for this request
+      DeadBro::WatchTracker.start_request_tracking if defined?(DeadBro::WatchTracker)
+
       # Start outgoing HTTP accumulation for this request
       Thread.current[:dead_bro_http_events] = []
 

data/lib/dead_bro/subscriber.rb

@@ -80,6 +80,8 @@ module DeadBro
         view_events = DeadBro::ViewRenderingSubscriber.stop_request_tracking
         view_performance = DeadBro::ViewRenderingSubscriber.analyze_view_performance(view_events)
 
+        watch_events = defined?(DeadBro::WatchTracker) ? DeadBro::WatchTracker.stop_request_tracking : []
+
         # Per-phase allocation attribution (under memory tracking) — which phase
         # allocated the request's objects (sql / view / elasticsearch).
         allocation_phases = if DeadBro.configuration.memory_tracking_enabled && defined?(DeadBro::MemoryPhaseTracker)
@@ -222,6 +224,7 @@ module DeadBro
           gc_pressure: gc_pressure,
           ar_instantiation_count: ar_instantiation_count,
           cpu_time_ms: cpu_time_ms,
+          watch_events: watch_events,
           logs: DeadBro.logger.logs
         }
         # force: true — the sampling decision (global or per-request-type) was
@@ -254,6 +257,7 @@ module DeadBro
       DeadBro::GcTracker.stop_request_tracking if defined?(DeadBro::GcTracker)
       DeadBro::ArObjectTracker.stop_request_tracking if defined?(DeadBro::ArObjectTracker)
       DeadBro::CpuTracker.stop_request_tracking if defined?(DeadBro::CpuTracker)
+      DeadBro::WatchTracker.stop_request_tracking if defined?(DeadBro::WatchTracker)
     rescue
       # Best effort — draining must never raise from the notifications callback.
     end

data/lib/dead_bro/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeadBro
-  VERSION = "0.2.29"
+  VERSION = "0.2.30"
 end

data/lib/dead_bro/watch_tracker.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module DeadBro
+  # Records user-defined timed blocks (DeadBro.watch) during an instrumented
+  # request or background job. Spans include wall duration, nesting depth, and
+  # SQL attributable to the block (delta from SqlSubscriber aggregates).
+  #
+  # SQL attribution: each span diffs the global SQL counter at block entry vs
+  # exit. Nested blocks each get their own diff; a parent span's sql_count /
+  # sql_duration_ms therefore includes queries run inside nested child spans
+  # (inclusive totals, not exclusive). Compare inner spans when you need
+  # per-block SQL; do not sum parent and child counts.
+  #
+  # Unlike DeadBro.analyze, watch spans are sent to the DeadBro backend as part
+  # of the normal request/job payload when watch_enabled is on.
+  module WatchTracker
+    THREAD_LOCAL_EVENTS_KEY = :dead_bro_watch_events
+    THREAD_LOCAL_ACTIVE_STACK_KEY = :dead_bro_watch_active_stack
+
+    # Deepest depth index still recorded — depths 0..MAX_DEPTH are kept, anything
+    # nested below that yields untracked.
+    MAX_DEPTH = 10
+    MAX_SPANS_PER_REQUEST = 50
+    MAX_LABEL_LENGTH = 200
+    MAX_TAGS = 5
+    MAX_TAG_VALUE_LENGTH = 100
+
+    module_function
+
+    def enabled?
+      DeadBro.configuration.watch_enabled?
+    rescue StandardError
+      false
+    end
+
+    def tracking_active?
+      Thread.current[THREAD_LOCAL_EVENTS_KEY].is_a?(Array)
+    rescue StandardError
+      false
+    end
+
+    def start_request_tracking
+      Thread.current[THREAD_LOCAL_EVENTS_KEY] = []
+      Thread.current[THREAD_LOCAL_ACTIVE_STACK_KEY] = []
+    end
+
+    def stop_request_tracking
+      events = Thread.current[THREAD_LOCAL_EVENTS_KEY]
+      Thread.current[THREAD_LOCAL_EVENTS_KEY] = nil
+      Thread.current[THREAD_LOCAL_ACTIVE_STACK_KEY] = nil
+      # compact drops reserved slots whose block never completed — can't happen
+      # for a lexical block, but keeps a nil out of the payload if it ever does.
+      events.is_a?(Array) ? events.compact : []
+    rescue StandardError
+      []
+    end
+
+    def watch(label = nil, **tags)
+      return yield unless block_given?
+      return yield unless enabled?
+      return yield unless tracking_active?
+
+      events = Thread.current[THREAD_LOCAL_EVENTS_KEY]
+      active_stack = Thread.current[THREAD_LOCAL_ACTIVE_STACK_KEY]
+      return yield unless events.is_a?(Array) && active_stack.is_a?(Array)
+
+      depth = active_stack.length
+      return yield if depth > MAX_DEPTH
+      return yield if events.length >= MAX_SPANS_PER_REQUEST
+
+      sanitized_label = sanitize_label(label)
+      sanitized_tags = sanitize_tags(tags)
+      start_offset_ms = compute_start_offset_ms
+      sql_before = sql_metrics_snapshot
+      block_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      frame = {
+        label: sanitized_label,
+        depth: depth,
+        tags: sanitized_tags,
+        start_offset_ms: start_offset_ms,
+        sql_before: sql_before,
+        block_start: block_start,
+        error: false,
+        exception_class: nil
+      }
+      # Reserve the slot on entry so spans come out in start order. Blocks only
+      # complete inner-first, so appending on completion would emit a nested span
+      # ahead of its own parent; the placeholder keeps parents before children.
+      # It also makes MAX_SPANS_PER_REQUEST count blocks still in flight.
+      frame[:slot] = events.length
+      events << nil
+      active_stack << frame
+
+      begin
+        yield
+      rescue StandardError => e
+        frame[:error] = true
+        # Anonymous classes (Class.new(StandardError)) have a nil name — leave the
+        # field unset rather than shipping an empty string the dashboard would
+        # render as a blank exception.
+        class_name = e.class.name
+        frame[:exception_class] = class_name[0, 200] if class_name
+        raise
+      ensure
+        active_stack.pop if active_stack.last.equal?(frame)
+        append_completed_span(events, frame)
+      end
+    end
+
+    def sanitize_label(label)
+      text = label.to_s.strip
+      text = "block" if text.empty?
+      (text.length > MAX_LABEL_LENGTH) ? text[0, MAX_LABEL_LENGTH] + "..." : text
+    rescue StandardError
+      "block"
+    end
+
+    def sanitize_tags(tags)
+      return {} unless tags.is_a?(Hash) && tags.any?
+
+      tags.first(MAX_TAGS).each_with_object({}) do |(key, value), out|
+        k = key.to_s.strip[0, 50]
+        next if k.empty?
+
+        v = value.to_s.strip
+        v = v[0, MAX_TAG_VALUE_LENGTH] + "..." if v.length > MAX_TAG_VALUE_LENGTH
+        out[k] = v
+      end
+    rescue StandardError
+      {}
+    end
+
+    def compute_start_offset_ms
+      tracking_start = Thread.current[DeadBro::TRACKING_START_TIME_KEY]
+      return 0.0 unless tracking_start
+
+      ((Time.now - tracking_start) * 1000.0).round(2)
+    rescue StandardError
+      0.0
+    end
+
+    def sql_metrics_snapshot
+      return {count: 0, duration_ms: 0.0} unless defined?(DeadBro::SqlSubscriber)
+
+      DeadBro::SqlSubscriber.current_sql_metrics
+    rescue StandardError
+      {count: 0, duration_ms: 0.0}
+    end
+
+    def append_completed_span(events, frame)
+      return unless events.is_a?(Array)
+
+      slot = frame[:slot]
+      return unless slot.is_a?(Integer) && slot < events.length
+
+      elapsed_ms = begin
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - frame[:block_start]) * 1000.0).round(2)
+      rescue StandardError
+        0.0
+      end
+
+      sql_after = sql_metrics_snapshot
+      sql_before = frame[:sql_before] || {count: 0, duration_ms: 0.0}
+      sql_count = [(sql_after[:count] || 0).to_i - (sql_before[:count] || 0).to_i, 0].max
+      sql_duration_ms = [
+        (sql_after[:duration_ms] || 0.0).to_f - (sql_before[:duration_ms] || 0.0).to_f,
+        0.0
+      ].max.round(2)
+
+      span = {
+        label: frame[:label],
+        duration_ms: elapsed_ms,
+        start_offset_ms: frame[:start_offset_ms],
+        depth: frame[:depth],
+        sql_count: sql_count,
+        sql_duration_ms: sql_duration_ms,
+        error: frame[:error] == true
+      }
+      span[:exception_class] = frame[:exception_class] if frame[:exception_class]
+      tags = frame[:tags]
+      span[:tags] = tags if tags.is_a?(Hash) && tags.any?
+
+      events[slot] = span
+    rescue StandardError
+      # Never raise from instrumentation
+    end
+  end
+end

data/lib/dead_bro.rb

@@ -29,6 +29,7 @@ module DeadBro
   autoload :Monitor, "dead_bro/monitor"
   autoload :MemoryDetails, "dead_bro/memory_details"
   autoload :Logger, "dead_bro/logger"
+  autoload :WatchTracker, "dead_bro/watch_tracker"
   begin
     require "dead_bro/railtie"
   rescue LoadError
@@ -458,4 +459,28 @@ module DeadBro
     raise error if error
     analysis_result
   end
+
+  # Time a named block during an instrumented request or background job.
+  #
+  # When watch_enabled is on and tracking is active (web request or job),
+  # records elapsed time, optional tags, nested SQL count/duration, and errors
+  # as watch_events in the APM payload for the Request Trace waterfall.
+  #
+  # Nested watch blocks: each span's sql_count/sql_duration_ms is the SQL that
+  # ran while that block was active. Parent spans include SQL from nested child
+  # spans (inclusive). Inner spans show their own slice; do not add parent and
+  # child SQL counts together.
+  #
+  # When disabled or outside an instrumented context, yields with no overhead
+  # beyond a single config check.
+  #
+  # Usage:
+  #   DeadBro.watch("load users") { User.where(active: true).load }
+  #   DeadBro.watch("sync billing", customer_id: user.id) { sync!(user) }
+  #
+  # Compare to DeadBro.analyze — analyze is local-only console profiling;
+  # watch spans are sent to the DeadBro dashboard when enabled.
+  def self.watch(label = nil, **tags, &block)
+    WatchTracker.watch(label, **tags, &block)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dead_bro
 version: !ruby/object:Gem::Version
-  version: 0.2.29
+  version: 0.2.30
 platform: ruby
 authors:
 - Emanuel Comsa
@@ -58,6 +58,7 @@ files:
 - lib/dead_bro/subscriber.rb
 - lib/dead_bro/version.rb
 - lib/dead_bro/view_rendering_subscriber.rb
+- lib/dead_bro/watch_tracker.rb
 - lib/generators/dead_bro/install/install_generator.rb
 - lib/generators/dead_bro/install/templates/dead_bro.rb
 homepage: https://www.deadbro.com