dead_bro 0.2.8 → 0.2.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d8e1d14cc8e5511d143de228afefcb1a7557b8ce0308b7302ba40f4bc78bc90
-  data.tar.gz: 1d215f5ff69110be5c10e965bcf2ac2f08f1f6cb9a2be72b602f143c3e3ac5e5
+  metadata.gz: 1ac04c555f3f82572e94327d09b90672869eb17c129deb87c78f746625cb5afd
+  data.tar.gz: 4639f701e7bd5dff8b36933e85b405dbbe43a2ccc664c94f16b6e2ea98987fda
 SHA512:
-  metadata.gz: 9cab5ed48ea05f086512683b1d8d9fdb05030328f4fb4cb908884f074bc23b361ba7914774106bb5f1eba511435cdb506b123b2c4d2ece41634b539e925576a9
-  data.tar.gz: '0695e7e7bc6f5835fde69586aa2bc03c134ca9a2515a4bda4e55a0c78242f776315e07018834a2ce66c9a828849c05d807c38e183f99ab77e00ac4d239144943'
+  metadata.gz: fee0d59a0362226babd057547b8138078d5ce3da4a75a3c5a2bbd175ee21b3043485e9f6c8e0b0a27a18c2373f10827fc7804f64c96888a41eea8d3c8eb8ea74
+  data.tar.gz: 1e044e7a275a5e52843119e00488a8a458e6d6f95420543014edd1074985bcdeebe1cbeef579e436a4eb31836eb6f9e24961c039851c4c82b2b0a76184cf23d2

data/README.md

@@ -1,8 +1,10 @@
 # DeadBro (Beta Version)
 
-Minimal APM for Rails apps. Automatically measures each controller action's total time, tracks SQL queries, monitors view rendering performance, tracks memory usage and detects leaks, monitors background jobs, and posts metrics to a remote endpoint with an API key read from your app's settings/credentials/env.
+Minimal APM for Rails apps. Automatically measures each controller action's total time, tracks SQL queries, monitors view rendering performance, tracks memory usage and detects leaks, monitors background jobs, and posts metrics to DeadBro.
 
-To use the gem you need to have a free account with [DeadBro - Rails APM](https://www.deadbro.com)
+**Current versions:** almost everything (sampling, exclusions, SQL EXPLAIN, memory toggles, control-plane collectors, enable/disable, and more) is configured in the [DeadBro](https://www.deadbro.com) web app. The API returns those settings on successful requests and the gem applies them in memory—no need to mirror them in Ruby unless you want optional code-based overrides.
+
+To use the gem you need a free account with [DeadBro - Rails APM](https://www.deadbro.com).
 
 ## Installation
 
@@ -16,21 +18,33 @@ gem "dead_bro", git: "https://github.com/rubydevro/dead_bro.git"
 
 By default, if Rails is present, DeadBro auto-subscribes to `process_action.action_controller` and posts metrics asynchronously.
 
-### Configuration settings
-
-You can set via an initializer:
+### Required: API key in your app
 
+Add an initializer (for example `config/initializers/dead_bro.rb`) and set your API key from the environment, [Rails credentials](https://guides.rubyonrails.org/security.html#custom-credentials), or another secret store:
 
 ```ruby
 DeadBro.configure do |config|
   config.api_key = ENV["DEAD_BRO_API_KEY"]
-  config.enabled = true
 end
 ```
 
+That is enough to start shipping metrics. Create or copy the key from your DeadBro account, then wire it into `DEAD_BRO_API_KEY` (or assign `config.api_key` directly).
+
+### Dashboard configuration
+
+Use the DeadBro UI to turn features on or off, set sample rates, define controller/job inclusions and exclusions, tune slow-query EXPLAIN, enable queue and system metrics, and adjust related limits. After you deploy the initializer above, those choices take effect when the gem receives them from the API (typically on the next successful metric or heartbeat response).
+
+### Optional local flags
+
+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
+
+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.
+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
 
@@ -70,22 +84,20 @@ end
 
 ## Excluding Controllers and Jobs
 
-You can exclude specific controllers and jobs from APM tracking.
+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::*" # wildcard supported
-  ]
-
-  config.excluded_controller_actions = [
+    "Admin::*",
     "UsersController#show",
     "Admin::ReportsController#index",
-    "Admin::*#*" # wildcard supported for controller and action
+    "Admin::*#*"
   ]
 
   config.excluded_jobs = [
@@ -96,39 +108,38 @@ end
 ```
 
 Notes:
-- Wildcards `*` are supported for controller and action (e.g., `Admin::*#*`).
-- Matching is done against full names like `UsersController`, `Admin::ReportsController#index`, `MyJob`.
+- 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. This is useful when you want to focus monitoring on a subset of your application.
+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 specific controller actions
-  config.exclusive_controller_actions = [
+  # Only track these controllers/actions (patterns can include #action or wildcards)
+  config.exclusive_controllers = [
     "UsersController#show",
     "UsersController#index",
-    "Admin::ReportsController#*", # all actions in this controller
-    "Api::*#*" # all actions in all Api controllers
+    "Admin::ReportsController#*",
+    "Api::*#*"
   ]
 
-  # Only track these specific jobs
   config.exclusive_jobs = [
     "PaymentProcessingJob",
     "EmailDeliveryJob",
-    "Admin::*" # all jobs in Admin namespace
+    "Admin::*"
   ]
 end
 ```
 
 ### How It Works
 
-- **If `exclusive_controller_actions` or `exclusive_jobs` is empty/not defined**: All controllers/actions/jobs are tracked (default behavior)
-- **If `exclusive_controller_actions` or `exclusive_jobs` is defined with values**: Only matching controllers/actions/jobs are tracked
-- **Exclusion takes precedence**: If something is in both `excluded_*` and `exclusive_*`, it will be excluded (exclusion is checked first)
+- **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
 
@@ -137,18 +148,6 @@ end
 - **Debugging**: Temporarily focus on specific controllers/jobs during investigation
 - **Compliance**: Track only operations that require monitoring for compliance reasons
 
-### Environment Variables
-
-You can also configure exclusive tracking via environment variables:
-
-```bash
-# Comma-separated list of controller#action patterns
-dead_bro_EXCLUSIVE_CONTROLLER_ACTIONS="UsersController#show,Admin::*#*"
-
-# Comma-separated list of job patterns
-dead_bro_EXCLUSIVE_JOBS="PaymentProcessingJob,EmailDeliveryJob"
-```
-
 ## SQL Query Tracking
 
 DeadBro automatically tracks SQL queries executed during each request and job. Each request will include a `sql_queries` array containing:
@@ -173,6 +172,8 @@ DeadBro can automatically run `EXPLAIN ANALYZE` on slow SQL queries to help you
 
 ### Configuration
 
+These options are usually set in the DeadBro UI. In Ruby:
+
 - **`explain_analyze_enabled`** (default: `false`) - Set to `true` to enable automatic EXPLAIN ANALYZE
 - **`slow_query_threshold_ms`** (default: `500`) - Queries taking longer than this threshold will have their execution plan captured
 
@@ -180,13 +181,10 @@ DeadBro can automatically run `EXPLAIN ANALYZE` on slow SQL queries to help you
 
 ```ruby
 DeadBro.configure do |config|
-  config.api_key = ENV['DEAD_BRO_API_KEY']
-  config.enabled = true
-  
   # Enable EXPLAIN ANALYZE for queries 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
@@ -232,8 +230,9 @@ By default, DeadBro uses **lightweight memory tracking** that has minimal perfor
 
 ### Configuration Options
 
+Usually managed in the dashboard; Ruby example:
+
 ```ruby
-# In your Rails configuration
 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)
@@ -279,7 +278,7 @@ Everything is **best effort** and designed to be **safe and low overhead**:
 
 ### Configuration
 
-You can enable or disable individual collectors and tune basic options via the standard `DeadBro.configure` block:
+Enable or disable collectors in the DeadBro app, or use `DeadBro.configure` for code-based overrides:
 
 ```ruby
 DeadBro.configure do |config|
@@ -389,6 +388,69 @@ The control plane job sends a single JSON payload roughly shaped like:
 Not all fields will be present in all environments; unsupported or unavailable metrics may be `null` or omitted, and any hard failures are captured in `error_class` / `error_message` fields per section.
 
 
+## One-Off Analysis with `DeadBro.analyze`
+
+Use `DeadBro.analyze` to profile any block of code inline — useful in the Rails console, rake tasks, or debug sessions. It tracks execution time, SQL queries, and memory usage without sending data to the DeadBro backend.
+
+```ruby
+result = DeadBro.analyze("load active users") do
+  User.where(active: true).includes(:profile).to_a
+end
+```
+
+Returns a `DeadBro::AnalysisResult` struct.
+
+### Return Value
+
+`DeadBro::AnalysisResult` exposes:
+
+| Member | Type | Description |
+|---|---|---|
+| `label` | String | Label passed to the block |
+| `total_time_ms` | Float | Wall time of the block |
+| `sql_count` | Integer | Number of SQL queries executed |
+| `sql_time_ms` | Float | Total SQL execution time |
+| `sql_queries` | Array | Per-query breakdown (see below) |
+| `memory_before_mb` | Float | RSS before block |
+| `memory_after_mb` | Float | RSS after block |
+| `memory_delta_mb` | Float | Memory change |
+| `memory_details` | Hash | GC stats, new objects, heap pages |
+
+**`sql_queries` is intentionally excluded from `inspect`/`to_s`** to avoid flooding the console with a long array. Access it explicitly when needed:
+
+```ruby
+result             # => #<DeadBro::AnalysisResult label="load active users" total_time_ms=42.3 ...>
+result.sql_queries # => [{sql: "SELECT ...", query_type: "SELECT", count: 3, total_time_ms: 12.1}, ...]
+```
+
+### Options
+
+```ruby
+DeadBro.analyze("my block", verbose: true) do
+  # verbose: true lowers the Rails log level to DEBUG and enables
+  # ActiveRecord.verbose_query_logs for the duration of the block
+  MyService.call
+end
+```
+
+### Helper methods
+
+```ruby
+result.most_queries    # top 5 query patterns by execution count
+result.longest_queries # top 5 query patterns by total_time_ms
+```
+
+Both return an array of query hashes (same shape as `sql_queries`):
+
+- `sql` — normalized SQL (literals replaced, whitespace collapsed)
+- `query_type` — e.g. `"SELECT"`, `"INSERT"`, `"UPDATE"`
+- `count` — how many times this pattern ran
+- `total_time_ms` — combined time across all occurrences
+
+### `sql_queries` fields
+
+`result.sql_queries` returns the full list. Each entry is a hash with the same fields as above.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/dead_bro/circuit_breaker.rb

@@ -25,15 +25,17 @@ module DeadBro
       @failure_count = 0
       @last_failure_time = nil
       @last_success_time = nil
+      @mutex = Mutex.new
     end
 
     def call(&block)
-      case @state
+      state = @mutex.synchronize { @state }
+      case state
       when CLOSED
         execute_with_monitoring(&block)
       when OPEN
         if should_attempt_reset?
-          @state = HALF_OPEN
+          @mutex.synchronize { @state = HALF_OPEN }
           execute_with_monitoring(&block)
         else
           :circuit_open
@@ -43,75 +45,93 @@ module DeadBro
       end
     end
 
-    attr_reader :state
+    def state
+      @mutex.synchronize { @state }
+    end
 
-    attr_reader :failure_count
+    def failure_count
+      @mutex.synchronize { @failure_count }
+    end
 
-    attr_reader :last_failure_time
+    def last_failure_time
+      @mutex.synchronize { @last_failure_time }
+    end
 
-    attr_reader :last_success_time
+    def last_success_time
+      @mutex.synchronize { @last_success_time }
+    end
 
     def reset!
-      @state = CLOSED
-      @failure_count = 0
-      @last_failure_time = nil
+      @mutex.synchronize do
+        @state = CLOSED
+        @failure_count = 0
+        @last_failure_time = nil
+      end
     end
 
     def open!
-      @state = OPEN
-      @last_failure_time = Time.now
+      @mutex.synchronize do
+        @state = OPEN
+        @last_failure_time = Time.now
+      end
     end
 
     def transition_to_half_open!
-      @state = HALF_OPEN
+      @mutex.synchronize { @state = HALF_OPEN }
     end
 
     def should_attempt_reset?
-      return false unless @last_failure_time
+      @mutex.synchronize do
+        return false unless @last_failure_time
+        (Time.now - @last_failure_time) >= @recovery_timeout
+      end
+    end
+
+    # Public entry points for callers that already know the outcome (e.g. the
+    # HTTP dispatcher thread). Preferred over `call(&block)` when the caller
+    # is doing its own error handling.
+    def record_success
+      @mutex.synchronize do
+        @failure_count = 0
+        @last_success_time = Time.now
+        @state = CLOSED
+      end
+    end
 
-      # Try to reset after recovery timeout
-      elapsed = Time.now - @last_failure_time
-      elapsed >= @recovery_timeout
+    def record_failure
+      @mutex.synchronize do
+        @failure_count += 1
+        @last_failure_time = Time.now
+        if @state == HALF_OPEN || @failure_count >= @failure_threshold
+          @state = OPEN
+        end
+      end
     end
 
     private
 
+    # Historical names kept as private aliases so existing specs and any
+    # internal callers that reach in via `send(:on_success)` still work.
+    alias_method :on_success, :record_success
+    alias_method :on_failure, :record_failure
+
     def execute_with_monitoring(&block)
       result = block.call
 
       if success?(result)
-        on_success
+        record_success
         result
       else
-        on_failure
+        record_failure
         result
       end
     rescue => e
-      on_failure
+      record_failure
       raise e
     end
 
     def success?(result)
-      # Consider 2xx status codes as success
       result.is_a?(Net::HTTPSuccess)
     end
-
-    def on_success
-      @failure_count = 0
-      @last_success_time = Time.now
-      @state = CLOSED
-    end
-
-    def on_failure
-      @failure_count += 1
-      @last_failure_time = Time.now
-
-      # If we're in half-open state and get a failure, go back to open
-      if @state == HALF_OPEN
-        @state = OPEN
-      elsif @failure_count >= @failure_threshold
-        @state = OPEN
-      end
-    end
   end
 end