dead_bro 0.2.29 → 0.2.31

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a338a291bd4ec9c69be1850484d683b67cca4bccd4efc29b73e8469130997cb
-  data.tar.gz: 9c77106ee1b182ebd76928929bca1ca143e9a06647fcb9f5cc4cf00b1c67490b
+  metadata.gz: b6c0f13b23ff342d0ea4365872e2f380a949a8aaf3fd69d98606336854d14c9c
+  data.tar.gz: a9b8a2fae51c26e7cd9b2f1d676c6742a5a5b4829f0c182417af7eabdf2581c6
 SHA512:
-  metadata.gz: 19af4bc9fc35ea4823a6a66fb20dd39e6fe41c778dd34a5b3d5d7109fac62b90170506f5c3d1359d864590b5e61fe61d3d8db79ca20be535bef80f7938801a2f
-  data.tar.gz: 30271ddbb549baf03d2acc8885dd45c19c49778893d427eeb79ef8e23b0b39467b5dbf65f6d47b84c2d555117ddf36929e604bdbde73171e46c27b9073ae36b9
+  metadata.gz: e70b0d0b091dfacf1db61ea287a47bb1944153968bc3f225c943baf6a195c099dfd88199e59a942230284f3cfc94dcbf207d942e03630ac14850f818c1dc0928
+  data.tar.gz: 1e5f8605da3bf8c418d4c16025be5a24b7f89af1ca47d7bb6c767f790205c498e3023543b739b1568156547c21b8cfaf2bf327c573d8177aad88049e395352f2

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/README.md

@@ -65,115 +65,9 @@ Use the DeadBro UI to turn features on or off, set sample rates, define controll
 
 You can still set `config.enabled` in Ruby if you need to force the integration off in a given environment before any remote settings arrive; otherwise the dashboard can control `enabled` like other remote settings.
 
-## Optional: configuration in Ruby
+## Request Sampling, Exclusions & Whitelisting
 
-The sections below describe the same knobs you can manage in the DeadBro app. Use them only when you want values in source control, per-environment initializer logic, or other overrides outside the UI.
-
-## Request Sampling
-
-DeadBro supports configurable request sampling to reduce the volume of metrics sent to your APM endpoint, which is useful for high-traffic applications. Prefer setting this in the DeadBro app; use Ruby if you need a local override.
-
-### Configuration
-
-Set the sample rate as a percentage (1-100):
-
-```ruby
-# Track 50% of requests
-DeadBro.configure do |config|
-  config.sample_rate = 50
-end
-
-# Track 10% of requests (useful for high-traffic apps)
-DeadBro.configure do |config|
-  config.sample_rate = 10
-end
-
-# Track all requests (default)
-DeadBro.configure do |config|
-  config.sample_rate = 100
-end
-```
-
-### How It Works
-
-- **Random Sampling**: Each request has a random chance of being tracked based on the sample rate
-- **Consistent Per-Request**: The sampling decision is made once per request and applies to all metrics for that request
-- **Debug Logging**: Skipped requests do not count towards the montly limit
-- **Error Tracking**: Errors are still tracked regardless of sampling
-
-### Use Cases
-
-- **High-Traffic Applications**: Reduce APM data volume and costs
-- **Development/Staging**: Sample fewer requests to reduce noise
-- **Performance Testing**: Track a subset of requests during load testing
-- **Cost Optimization**: Balance monitoring coverage with data costs
-
-
-## Excluding Controllers and Jobs
-
-You can exclude specific controllers and jobs from APM tracking (dashboard first; Ruby optional).
-
-### Configuration
-
-
-```ruby
-DeadBro.configure do |config|
-  # Controller-only or controller#action patterns in one list (wildcards supported)
-  config.excluded_controllers = [
-    "HealthChecksController",
-    "Admin::*",
-    "UsersController#show",
-    "Admin::ReportsController#index",
-    "Admin::*#*"
-  ]
-
-  config.excluded_jobs = [
-    "ActiveStorage::AnalyzeJob",
-    "Admin::*"
-  ]
-end
-```
-
-Notes:
-- Wildcards `*` are supported (e.g., `Admin::*`, `Admin::*#*`).
-- Matching uses full names like `UsersController`, `Admin::ReportsController#index`, `MyJob`.
-
-## Exclusive Tracking (Whitelist Mode)
-
-You can configure DeadBro to **only** track specific controllers, actions, or jobs. Prefer the dashboard; use Ruby for overrides.
-
-### Configuration
-
-```ruby
-DeadBro.configure do |config|
-  # Only track these controllers/actions (patterns can include #action or wildcards)
-  config.exclusive_controllers = [
-    "UsersController#show",
-    "UsersController#index",
-    "Admin::ReportsController#*",
-    "Api::*#*"
-  ]
-
-  config.exclusive_jobs = [
-    "PaymentProcessingJob",
-    "EmailDeliveryJob",
-    "Admin::*"
-  ]
-end
-```
-
-### How It Works
-
-- **If `exclusive_controllers` or `exclusive_jobs` is empty/not defined**: All controllers/actions/jobs are tracked (default behavior)
-- **If `exclusive_controllers` or `exclusive_jobs` is defined with values**: Only matching controllers/actions/jobs are tracked
-- **Exclusion takes precedence**: If something matches both `excluded_*` and `exclusive_*`, it is excluded (exclusion is checked first)
-
-### Use Cases
-
-- **Focus on Critical Paths**: Monitor only your most important endpoints
-- **Cost Optimization**: Track only specific high-value operations
-- **Debugging**: Temporarily focus on specific controllers/jobs during investigation
-- **Compliance**: Track only operations that require monitoring for compliance reasons
+To control data volume, DeadBro supports request sampling (track a percentage of requests), excluding specific controllers/jobs from tracking, and whitelisting (tracking *only* specific controllers/jobs). All of this is configured in the DeadBro dashboard — sample rate, `excluded_controllers`/`excluded_jobs`, and `exclusive_controllers`/`exclusive_jobs` patterns (wildcards like `Admin::*` and `Admin::*#*` supported). Exclusion always takes precedence over whitelisting when a pattern matches both.
 
 ## SQL Query Tracking
 
@@ -198,43 +92,19 @@ DeadBro can automatically capture the query plan (`EXPLAIN`) of slow SELECT quer
 - **Value scrubbing**: quoted string literals echoed in plan text (e.g. `Filter: email = 'a@b.com'`) are replaced with `?` before the plan leaves your app.
 - **Bounded overhead**: plans are captured on background threads (max 3 concurrent per request); at request end DeadBro waits at most 0.5s for stragglers, then drops them.
 
-### How It Works
-
-- **Automatic Detection**: when a SELECT exceeds `slow_query_threshold_ms`, DeadBro captures its plan in the background
-- **Database Support**: PostgreSQL, MySQL, SQLite (`EXPLAIN QUERY PLAN`), and any adapter with a standard `EXPLAIN`
-
 ### Configuration
 
-- **`explain_analyze_enabled`** (default: `false`) - local opt-in for automatic EXPLAIN plan capture. Must be set in Ruby; the DeadBro UI toggle can only turn capture off, not on.
-- **`slow_query_threshold_ms`** (default: `500`) - queries taking longer than this threshold will have their execution plan captured
+- **`explain_analyze_enabled`** (default: `false`) — this is the one setting that must be turned on in Ruby; the dashboard toggle can only turn capture *off*, never on, as an extra safety rail:
 
-### Example Configuration
-
-```ruby
-DeadBro.configure do |config|
-  # Capture EXPLAIN plans for SELECTs slower than 500ms
-  config.explain_analyze_enabled = true
-  config.slow_query_threshold_ms = 500
-
-  # Or use a higher threshold for production
-  # config.slow_query_threshold_ms = 1000  # Only explain queries > 1 second
-end
-```
+  ```ruby
+  DeadBro.configure do |config|
+    config.explain_analyze_enabled = true
+  end
+  ```
 
-### What You Get
+- Everything else — the `slow_query_threshold_ms` cutoff and enabling/disabling the feature — is managed from the dashboard.
 
-When a slow query is detected, the `explain_plan` field in the SQL query data will contain:
-- **PostgreSQL / MySQL**: `EXPLAIN` output — the planner's chosen strategy, estimated costs and row counts
-- **SQLite**: `EXPLAIN QUERY PLAN` output
-- **Other databases**: standard `EXPLAIN` output
-
-This execution plan helps you:
-- Identify missing indexes
-- Understand query execution order
-- Spot full table scans
-- Optimize JOIN operations
-
-Because the statement is not executed, plans show the planner's *estimates* rather than actual runtimes — usually exactly what you need to spot a missing index or an unexpected sequential scan.
+When a slow query is detected, the `explain_plan` field in the SQL query data contains the database's `EXPLAIN` (or `EXPLAIN QUERY PLAN` on SQLite) output — the planner's chosen strategy, estimated costs and row counts — useful for spotting missing indexes or unexpected sequential scans. Because the statement is never executed, plans show estimates rather than actual runtimes.
 
 ## View Rendering Tracking
 
@@ -259,20 +129,7 @@ By default, DeadBro uses **lightweight memory tracking** that has minimal perfor
 - **GC Efficiency Analysis**: Monitor garbage collection effectiveness
 - **Zero Allocation Tracking**: No object allocation tracking by default (can be enabled)
 
-### Configuration Options
-
-Usually managed in the dashboard; Ruby example:
-
-```ruby
-DeadBro.configure do |config|
-  config.memory_tracking_enabled = true        # Enable lightweight memory tracking (default: true)
-  config.allocation_tracking_enabled = false   # Enable detailed allocation tracking (default: false)
-  config.allocation_sample_rate = 100          # % of requests that pay for allocation tracking when enabled (1-100, default: 100)
-
-  # Sampling configuration
-  config.sample_rate = 100                     # Percentage of requests to track (1-100, default: 100)
-end
-```
+`memory_tracking_enabled`, `allocation_tracking_enabled`, and `allocation_sample_rate` are all managed from the dashboard.
 
 **Performance Impact:**
 - **Lightweight mode** (`memory_tracking_enabled`, ~0.1ms overhead per request): RSS before/after, GC pressure, the retained-vs-transient signals (`heap_live_slots_growth`, `malloc_increase_bytes`), and per-phase allocation attribution (`allocation_phases` — which of `sql`/`view`/`elasticsearch` allocated the request's objects).
@@ -310,25 +167,7 @@ Everything is **best effort** and designed to be **safe and low overhead**:
 
 ### Configuration
 
-Enable or disable collectors in the DeadBro app, or use `DeadBro.configure` for code-based overrides:
-
-```ruby
-DeadBro.configure do |config|
-  # Enable the periodic job queue monitor (disabled by default)
-  config.job_queue_monitoring_enabled = true
-
-  # Enable best-effort collectors (all default to false)
-  config.enable_db_stats      = true   # ActiveRecord pool + ping latency
-  config.enable_process_stats = true   # pid, hostname, RSS, GC, threads, fds
-  config.enable_system_stats  = true   # CPU%, memory, disk, network
-
-  # Filesystem paths to report disk usage for (default: ["/"])
-  config.disk_paths = ["/", "/var"]
-
-  # Network interfaces to ignore when computing rx/tx stats
-  config.interfaces_ignore = %w[lo docker0]
-end
-```
+Enable or disable the job queue monitor and the individual collectors (`enable_db_stats`, `enable_process_stats`, `enable_system_stats`), plus `disk_paths` and `interfaces_ignore`, from the DeadBro dashboard.
 
 ### Example Payload Shape
 

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)
@@ -162,6 +164,7 @@ module DeadBro
               duration_ms: duration_ms,
               rails_env: DeadBro.env,
               host: DeadBro.safe_hostname,
+              request_host: safe_request_host(data),
               process_kind: DeadBro.process_kind,
               params: safe_params(data),
               user_agent: safe_user_agent(data),
@@ -195,6 +198,7 @@ module DeadBro
           view_runtime_ms: data[:view_runtime],
           db_runtime_ms: data[:db_runtime],
           host: DeadBro.safe_hostname,
+          request_host: safe_request_host(data),
           rails_env: DeadBro.env,
           process_kind: DeadBro.process_kind,
           params: safe_params(data),
@@ -222,6 +226,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 +259,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
@@ -326,6 +332,37 @@ module DeadBro
       end
     end
 
+    # The domain the request was served on (request.host) — distinct from `host`,
+    # which is the machine's OS hostname. Lets one app that answers on several
+    # domains be sliced by domain in the dashboard. Port and userinfo are dropped;
+    # value is lowercased so "Example.com" and "example.com" aren't two rows.
+    def self.safe_request_host(data)
+      raw =
+        if data[:request] && data[:request].respond_to?(:host)
+          data[:request].host
+        elsif data[:headers]
+          headers = data[:headers]
+          if headers.respond_to?(:[])
+            headers["HTTP_HOST"] || headers["Host"] || headers["host"]
+          elsif headers.respond_to?(:env)
+            headers.env && headers.env["HTTP_HOST"]
+          end
+        elsif data[:env].is_a?(Hash)
+          data[:env]["HTTP_HOST"]
+        end
+
+      host = sanitize_string(raw)
+      return "" if host.empty?
+
+      # Strip any userinfo@ and a trailing :port so only the hostname remains.
+      # Only a numeric trailing port is removed, so IPv6 literals ([::1]) survive.
+      host = host.split("@").last.to_s
+      host = host.sub(/:\d+\z/, "")
+      host.downcase[0, 255]
+    rescue
+      ""
+    end
+
     def self.safe_user_agent(data)
       begin
         # Prefer request object if available

data/lib/dead_bro/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeadBro
-  VERSION = "0.2.29"
+  VERSION = "0.2.31"
 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.31
 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