apm_bro 0.1.15 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26626be56405c7aa4561db094b0e1bf27b1469cef67275786ec1ece6e28947e3
-  data.tar.gz: c07ec1b39ff873b5cccfa909fb726aa5971bc87b6abdae8a59de4bd4550b898b
+  metadata.gz: 2fde98f2cfbdbc149e9a10f3000a56c14fb35238bd09e0dba8b7cb17db7095b2
+  data.tar.gz: 7b995dbae659d5e24982c1c2da7b2b50e644ca4b275bbc5fef410118bfc6a385
 SHA512:
-  metadata.gz: 8c8dc70fec2841c841e71b945f9e6db3aaf40f35bd7e750f3386130829a0733e44e91c16da05b0eeb5e52175bad335af9990942ed66385ff5926460fc98b64f9
-  data.tar.gz: 356a4e343d70b3bac7aee65d285fabe765dbb91d0ba74c4a2b594ca6459e13b7cfc68e8a96fbe43c525f5252e4a3f0692028dbcd38c01a0d7ad0d52b6d4cbda5
+  metadata.gz: bcb1b5ce3f643b0b7ef971c3a219884892741664beefa28ae6c4111076e9eb393f8b10840ba655835061f9a481f07c35fc234f9e0bd787bcbceb150a08f0ba11
+  data.tar.gz: 9f88694746c9ac3ba2dc463481ca26796bd04306817a44b44e7a596ea2c94aad4f7bb4d84c6cffa0470b614ba09b6da47379d8ce0325b3cc9e1f191fe949c830

data/FEATURES.md

@@ -0,0 +1,338 @@
+# ApmBro Feature List
+
+A comprehensive feature list for comparing ApmBro with other APM (Application Performance Monitoring) tools.
+
+## Core Architecture
+
+- **Rails Integration**: Automatic subscription to Rails events via ActiveSupport::Notifications
+- **Zero-Configuration Setup**: Works out of the box with minimal configuration
+- **Asynchronous Metrics Posting**: Non-blocking HTTP requests using background threads
+- **Thread-Local Storage**: Per-request metric collection using thread-local variables
+- **Circuit Breaker Pattern**: Built-in circuit breaker to prevent cascading failures when APM endpoint is down
+- **Deploy Tracking**: Automatic deploy ID resolution from multiple sources (Rails settings, ENV vars, Heroku, Git)
+
+## Request Tracking
+
+### Controller Action Monitoring
+- **Automatic Tracking**: Tracks all controller actions automatically
+- **Request Duration**: Measures total request processing time
+- **HTTP Method & Path**: Captures HTTP method and request path
+- **Status Codes**: Tracks HTTP response status codes
+- **View Runtime**: Separate tracking of view rendering time
+- **Database Runtime**: Separate tracking of database query time
+- **Request Parameters**: Captures request parameters (with sensitive data filtering)
+- **User Agent**: Tracks user agent strings
+- **User ID Extraction**: Extracts authenticated user ID (supports Warden)
+- **Environment Context**: Tracks Rails environment (development, staging, production)
+
+### Request Sampling
+- **Configurable Sample Rate**: Percentage-based sampling (1-100%)
+- **Random Sampling**: Each request has random chance of being tracked
+- **Consistent Per-Request**: Sampling decision applies to all metrics for a request
+- **Error Override**: Errors are always tracked regardless of sampling
+- **Cost Optimization**: Reduces data volume and costs for high-traffic applications
+
+### Exclusion Rules
+- **Controller Exclusion**: Exclude entire controllers from tracking
+- **Action Exclusion**: Exclude specific controller#action combinations
+- **Wildcard Support**: Pattern matching with `*` wildcards (e.g., `Admin::*`, `Admin::*#*`)
+- **Job Exclusion**: Exclude specific background jobs from tracking
+- **Flexible Configuration**: Configure via initializer, Rails settings, or environment variables
+
+## SQL Query Tracking
+
+### Query Details
+- **Full SQL Tracking**: Captures all SQL queries executed during requests and jobs
+- **Query Sanitization**: Automatically sanitizes SQL to remove sensitive data
+- **Query Name**: Tracks query names (e.g., "User Load", "User Update")
+- **Duration Measurement**: Precise query execution time in milliseconds
+- **Cache Detection**: Identifies cached queries
+- **Connection ID**: Tracks database connection ID
+- **Call Stack Traces**: Full backtrace showing where queries were executed
+- **Object Allocations**: Optional tracking of object allocations per query
+
+### Query Performance Analysis
+- **Slow Query Detection**: Configurable threshold for identifying slow queries
+- **EXPLAIN ANALYZE**: Automatic execution plan capture for slow queries
+- **Background Execution**: EXPLAIN ANALYZE runs in separate thread (non-blocking)
+- **Multi-Database Support**: Works with PostgreSQL, MySQL, SQLite, and others
+- **Smart Filtering**: Automatically skips transaction queries (BEGIN, COMMIT, ROLLBACK)
+- **Execution Plan Details**: 
+  - PostgreSQL: Full EXPLAIN ANALYZE with buffer usage statistics
+  - MySQL: EXPLAIN ANALYZE with actual execution times
+  - SQLite: EXPLAIN QUERY PLAN output
+- **Query Optimization Insights**: Helps identify missing indexes, full table scans, JOIN issues
+
+## View Rendering Tracking
+
+### View Performance
+- **Template Rendering**: Tracks main template rendering
+- **Partial Rendering**: Tracks partial template rendering with cache key information
+- **Collection Rendering**: Tracks collection rendering (partials in loops)
+- **Rendering Duration**: Precise timing for each view component
+- **Virtual Path Tracking**: Tracks view virtual paths
+- **Layout Information**: Captures layout usage
+
+### View Analysis
+- **Slow View Detection**: Identifies the slowest rendering views
+- **Frequency Analysis**: Tracks most frequently rendered views
+- **Cache Hit Rate**: Calculates cache hit rates for partials
+- **Collection Cache Analysis**: Tracks cache hit rates for collection rendering
+- **Performance Metrics**: 
+  - Total views rendered per request
+  - Total view rendering duration
+  - Average view rendering duration
+  - Breakdown by view type (template, partial, collection)
+
+## Memory Tracking & Leak Detection
+
+### Lightweight Memory Tracking (Default)
+- **Memory Usage Monitoring**: Tracks memory consumption per request using GC stats
+- **Memory Growth Tracking**: Measures memory growth during request processing
+- **GC Statistics**: Tracks garbage collection count and heap pages
+- **Minimal Performance Impact**: ~0.1ms overhead per request
+- **Memory Before/After**: Captures memory state at request start and end
+
+### Detailed Allocation Tracking (Optional)
+- **Object Allocation Tracking**: Detailed tracking of object allocations (disabled by default)
+- **Allocation Sampling**: Configurable sampling rate for allocations
+- **Large Object Detection**: Identifies objects larger than 1MB threshold
+- **Memory Snapshots**: Periodic memory snapshots during request processing
+- **Object Count Tracking**: Tracks object counts before and after requests
+- **Performance Impact**: ~2-5ms overhead per request (only when enabled)
+
+### Memory Leak Detection
+- **Pattern Detection**: Detects growing memory patterns over time
+- **GC Efficiency Analysis**: Monitors garbage collection effectiveness
+- **Heap Page Tracking**: Tracks heap page growth
+- **Request Correlation**: Correlates memory growth with specific controllers/actions
+
+## Background Job Tracking
+
+### Job Execution Monitoring
+- **ActiveJob Integration**: Automatic tracking when ActiveJob is available
+- **Job Class Tracking**: Tracks job class names
+- **Job ID**: Captures unique job identifiers
+- **Queue Name**: Tracks which queue processed the job
+- **Job Arguments**: Captures job arguments (with sensitive data filtering)
+- **Duration Measurement**: Precise job execution time in milliseconds
+- **Status Tracking**: Tracks job status (completed or failed)
+
+### Job Error Tracking
+- **Exception Capture**: Captures exceptions from failed jobs
+- **Exception Class**: Tracks exception class names
+- **Exception Messages**: Captures exception messages (truncated to 1000 chars)
+- **Backtraces**: Full exception backtraces (first 50 lines)
+- **SQL Query Context**: Includes SQL queries executed during failed jobs
+- **Memory Context**: Includes memory usage during job execution
+
+### Job SQL Tracking
+- **SQL Query Tracking**: Tracks all SQL queries executed during job processing
+- **Query Details**: Same detailed SQL tracking as request tracking
+- **Query Context**: Full context of database operations in background jobs
+
+## Cache Tracking
+
+### Cache Operations
+- **Read Operations**: Tracks cache read operations
+- **Write Operations**: Tracks cache write operations
+- **Delete Operations**: Tracks cache delete operations
+- **Existence Checks**: Tracks cache existence checks
+- **Fetch Operations**: Tracks cache fetch with hit/miss detection
+- **Multi-Read Operations**: Tracks cache read_multi operations
+- **Multi-Write Operations**: Tracks cache write_multi operations
+- **Cache Generation**: Tracks cache generation events
+
+### Cache Analysis
+- **Cache Hit Detection**: Identifies cache hits vs misses
+- **Cache Key Tracking**: Tracks cache keys (truncated to 200 chars)
+- **Store Information**: Identifies which cache store was used
+- **Namespace Tracking**: Tracks cache namespaces
+- **Duration Measurement**: Precise timing for each cache operation
+- **Hit Rate Calculation**: Calculates cache hit rates per request
+
+## Redis Tracking
+
+### Redis Command Tracking
+- **Command Monitoring**: Tracks all Redis commands executed
+- **Command Name**: Captures Redis command names (GET, SET, etc.)
+- **Key Tracking**: Tracks Redis keys (truncated to 200 chars)
+- **Argument Count**: Tracks number of arguments per command
+- **Database Selection**: Tracks which Redis database is used
+- **Duration Measurement**: Precise timing for each Redis command
+- **Error Tracking**: Captures Redis command errors
+
+### Advanced Redis Features
+- **Pipeline Support**: Tracks Redis pipeline operations with command counts
+- **Multi/Transaction Support**: Tracks Redis MULTI/EXEC transactions
+- **ActiveSupport Integration**: Subscribes to ActiveSupport::Notifications for Redis events
+- **Client Instrumentation**: Direct instrumentation of Redis::Client for comprehensive coverage
+
+## Error Tracking
+
+### Exception Handling
+- **Automatic Exception Capture**: Captures exceptions from controller actions
+- **Exception Class**: Tracks exception class names
+- **Exception Messages**: Captures exception messages (truncated to 1000 chars)
+- **Full Backtraces**: Captures complete exception backtraces (first 50 lines)
+- **Request Context**: Includes full request context with exceptions
+- **Error Flagging**: Errors are marked and always tracked (even with sampling)
+
+### Error Context
+- **Controller/Action**: Identifies where the error occurred
+- **Request Parameters**: Includes request parameters at time of error
+- **User Information**: Includes user ID if available
+- **SQL Queries**: Includes SQL queries executed before error
+- **Memory State**: Includes memory usage at time of error
+- **Log Messages**: Includes application logs captured during request
+
+## HTTP Instrumentation
+
+### Outgoing HTTP Tracking
+- **HTTP Request Tracking**: Tracks outgoing HTTP requests (via middleware)
+- **Request Context**: Captures HTTP request details
+- **Response Context**: Captures HTTP response details
+- **Duration Measurement**: Tracks HTTP request duration
+
+## Configuration & Flexibility
+
+### Configuration Options
+- **API Key Management**: Multiple sources (config, Rails credentials, ENV)
+- **Endpoint Configuration**: Configurable endpoint URL
+- **Timeout Settings**: Configurable open and read timeouts
+- **Enable/Disable Toggle**: Can be enabled/disabled via configuration
+- **Environment Detection**: Automatic Rails environment detection
+
+### Circuit Breaker Configuration
+- **Failure Threshold**: Configurable failure threshold (default: 3)
+- **Recovery Timeout**: Configurable recovery timeout (default: 60 seconds)
+- **Retry Timeout**: Configurable retry timeout (default: 300 seconds)
+- **Enable/Disable**: Can enable/disable circuit breaker
+
+### Memory Tracking Configuration
+- **Memory Tracking Toggle**: Enable/disable memory tracking
+- **Allocation Tracking Toggle**: Enable/disable detailed allocation tracking
+- **Sampling Configuration**: Configurable request sampling rate
+
+### Query Analysis Configuration
+- **Slow Query Threshold**: Configurable threshold in milliseconds (default: 500ms)
+- **EXPLAIN ANALYZE Toggle**: Enable/disable automatic EXPLAIN ANALYZE
+
+## Data Safety & Privacy
+
+### Data Sanitization
+- **SQL Sanitization**: Automatically sanitizes SQL queries
+- **Parameter Filtering**: Filters sensitive parameters (password, token, secret, key)
+- **Argument Truncation**: Limits and truncates job arguments
+- **Key Truncation**: Truncates cache and Redis keys to 200 characters
+- **Value Truncation**: Recursively truncates nested values to prevent huge payloads
+- **String Limits**: Limits string values (e.g., user agent to 200 chars, messages to 1000 chars)
+
+### Data Limits
+- **Array Limits**: Limits array sizes (e.g., first 10 job arguments, first 5 array elements)
+- **Hash Limits**: Limits hash key counts (e.g., first 20 hash keys, first 30 params)
+- **Backtrace Limits**: Limits backtraces to first 50 lines
+- **Allocation Limits**: Limits allocations tracked per request (max 1000)
+
+## Performance & Reliability
+
+### Performance Optimizations
+- **Asynchronous Posting**: Non-blocking HTTP requests
+- **Lightweight Default Mode**: Minimal overhead in default configuration
+- **Sampling Support**: Reduces data volume for high-traffic applications
+- **Thread-Local Storage**: Efficient per-request data collection
+- **Background EXPLAIN**: EXPLAIN ANALYZE runs in background thread
+
+### Reliability Features
+- **Circuit Breaker**: Prevents cascading failures
+- **Error Handling**: Comprehensive error handling to prevent instrumentation failures
+- **Graceful Degradation**: Continues working even if some features fail
+- **Timeout Protection**: Configurable timeouts prevent hanging requests
+
+## Integration & Compatibility
+
+### Framework Support
+- **Rails Integration**: Full Rails integration via Railtie
+- **ActiveSupport Notifications**: Uses ActiveSupport::Notifications for event subscription
+- **ActiveRecord Integration**: Tracks ActiveRecord SQL queries
+- **ActiveJob Integration**: Tracks ActiveJob background jobs
+- **ActionView Integration**: Tracks ActionView rendering
+
+### Database Support
+- **PostgreSQL**: Full support with EXPLAIN ANALYZE
+- **MySQL**: Full support with EXPLAIN ANALYZE
+- **SQLite**: Full support with EXPLAIN QUERY PLAN
+- **Other Databases**: Basic support with standard EXPLAIN
+
+### Cache Store Support
+- **All Cache Stores**: Works with any Rails cache store
+- **Multi-Store Support**: Tracks cache operations across different stores
+
+### Redis Support
+- **Redis Gem**: Works with redis gem
+- **Client Instrumentation**: Direct instrumentation of Redis::Client
+- **Pipeline Support**: Tracks Redis pipelines
+- **Transaction Support**: Tracks Redis MULTI/EXEC transactions
+
+## Logging & Debugging
+
+### Application Logging
+- **Log Capture**: Captures application logs during request processing
+- **Log Context**: Includes logs in metric payloads
+- **Debug Logging**: Optional debug logging for skipped requests
+
+## Deployment & Environment
+
+### Deploy Tracking
+- **Deploy ID Resolution**: Multiple sources for deploy identification
+  - Explicit configuration
+  - Rails settings/credentials
+  - Environment variables (APM_BRO_DEPLOY_ID, GIT_REV)
+  - Heroku (HEROKU_SLUG_COMMIT)
+  - Process-stable UUID fallback
+- **Revision Tracking**: Includes deploy/revision ID in all metric payloads
+
+### Environment Support
+- **Rails Environment**: Automatic Rails environment detection
+- **Rack Environment**: Fallback to RACK_ENV or RAILS_ENV
+- **Environment Context**: Includes environment in all metric payloads
+
+## Data Collection & Transmission
+
+### Metric Payload Structure
+- **Structured Data**: Well-structured JSON payloads
+- **Event Names**: Descriptive event names for different metric types
+- **Timestamp Tracking**: ISO8601 timestamps for all metrics
+- **Metadata**: Rich metadata including environment, host, deploy ID
+
+### HTTP Client
+- **HTTPS Support**: Secure HTTPS communication
+- **Bearer Token Auth**: API key authentication via Bearer tokens
+- **JSON Encoding**: JSON-encoded payloads
+- **Custom Headers**: Proper Content-Type and Authorization headers
+
+## Comparison-Ready Features
+
+### Unique Differentiators
+1. **Automatic EXPLAIN ANALYZE**: Background execution plan capture for slow queries
+2. **Lightweight Memory Tracking**: Low-overhead memory monitoring by default
+3. **Comprehensive Cache Tracking**: Detailed cache operation tracking
+4. **Redis Instrumentation**: Full Redis command tracking including pipelines
+5. **View Rendering Analysis**: Detailed view performance analysis with cache hit rates
+6. **Flexible Exclusion Rules**: Wildcard support for controller/job exclusion
+7. **Request Sampling**: Configurable percentage-based sampling
+8. **Circuit Breaker**: Built-in resilience for APM endpoint failures
+9. **Multi-Source Configuration**: Flexible configuration from multiple sources
+10. **Deploy Tracking**: Automatic deploy ID resolution from multiple sources
+
+### Standard APM Features
+- Request/response tracking
+- SQL query tracking
+- Error tracking
+- Background job tracking
+- Memory tracking
+- Performance metrics
+- Exception handling
+- User context
+- Environment tracking
+

data/README.md

@@ -99,6 +99,56 @@ Notes:
 - Wildcards `*` are supported for controller and action (e.g., `Admin::*#*`).
 - Matching is done against full names like `UsersController`, `Admin::ReportsController#index`, `MyJob`.
 
+## Exclusive Tracking (Whitelist Mode)
+
+You can configure ApmBro to **only** track specific controllers, actions, or jobs. This is useful when you want to focus monitoring on a subset of your application.
+
+### Configuration
+
+```ruby
+ApmBro.configure do |config|
+  # Only track these specific controller actions
+  config.exclusive_controller_actions = [
+    "UsersController#show",
+    "UsersController#index",
+    "Admin::ReportsController#*", # all actions in this controller
+    "Api::*#*" # all actions in all Api controllers
+  ]
+
+  # Only track these specific jobs
+  config.exclusive_jobs = [
+    "PaymentProcessingJob",
+    "EmailDeliveryJob",
+    "Admin::*" # all jobs in Admin namespace
+  ]
+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)
+
+### 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
+
+### Environment Variables
+
+You can also configure exclusive tracking via environment variables:
+
+```bash
+# Comma-separated list of controller#action patterns
+APM_BRO_EXCLUSIVE_CONTROLLER_ACTIONS="UsersController#show,Admin::*#*"
+
+# Comma-separated list of job patterns
+APM_BRO_EXCLUSIVE_JOBS="PaymentProcessingJob,EmailDeliveryJob"
+```
+
 ## SQL Query Tracking
 
 ApmBro automatically tracks SQL queries executed during each request and job. Each request will include a `sql_queries` array containing:
@@ -108,6 +158,54 @@ ApmBro automatically tracks SQL queries executed during each request and job. Ea
 - `cached` - Whether the query was cached
 - `connection_id` - Database connection ID
 - `trace` - Call stack showing where the query was executed
+- `explain_plan` - Query execution plan (when EXPLAIN ANALYZE is enabled, see below)
+
+## Automatic EXPLAIN ANALYZE for Slow Queries
+
+ApmBro can automatically run `EXPLAIN ANALYZE` on slow SQL queries to help you understand query performance and identify optimization opportunities. This feature runs in the background and doesn't block your application requests.
+
+### How It Works
+
+- **Automatic Detection**: When a query exceeds the configured threshold, ApmBro automatically captures its execution plan
+- **Background Execution**: EXPLAIN ANALYZE runs in a separate thread using a dedicated database connection, so it never blocks your application
+- **Database Support**: Works with PostgreSQL, MySQL, SQLite, and other databases
+- **Smart Filtering**: Automatically skips transaction queries (BEGIN, COMMIT, ROLLBACK) and other queries that don't benefit from EXPLAIN
+
+### Configuration
+
+- **`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
+
+### Example Configuration
+
+```ruby
+ApmBro.configure do |config|
+  config.api_key = ENV['APM_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
+```
+
+### What You Get
+
+When a slow query is detected, the `explain_plan` field in the SQL query data will contain:
+- **PostgreSQL**: Full EXPLAIN ANALYZE output with buffer usage statistics
+- **MySQL**: EXPLAIN ANALYZE output showing actual execution times
+- **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
+- Analyze buffer and cache usage (PostgreSQL)
 
 ## View Rendering Tracking
 

data/lib/apm_bro/configuration.rb

@@ -4,7 +4,7 @@ module ApmBro
   class Configuration
     DEFAULT_ENDPOINT_PATH = "/v1/metrics"
 
-    attr_accessor :api_key, :endpoint_url, :open_timeout, :read_timeout, :enabled, :ruby_dev, :memory_tracking_enabled, :allocation_tracking_enabled, :circuit_breaker_enabled, :circuit_breaker_failure_threshold, :circuit_breaker_recovery_timeout, :circuit_breaker_retry_timeout, :sample_rate, :excluded_controllers, :excluded_jobs, :excluded_controller_actions, :deploy_id
+    attr_accessor :api_key, :endpoint_url, :open_timeout, :read_timeout, :enabled, :ruby_dev, :memory_tracking_enabled, :allocation_tracking_enabled, :circuit_breaker_enabled, :circuit_breaker_failure_threshold, :circuit_breaker_recovery_timeout, :circuit_breaker_retry_timeout, :sample_rate, :excluded_controllers, :excluded_jobs, :excluded_controller_actions, :exclusive_controller_actions, :exclusive_jobs, :deploy_id, :slow_query_threshold_ms, :explain_analyze_enabled
 
     def initialize
       @api_key = nil
@@ -23,7 +23,11 @@ module ApmBro
       @excluded_controllers = []
       @excluded_jobs = []
       @excluded_controller_actions = []
+      @exclusive_controller_actions = []
+      @exclusive_jobs = []
       @deploy_id = resolve_deploy_id
+      @slow_query_threshold_ms = 500 # Default: 500ms
+      @explain_analyze_enabled = false # Enable EXPLAIN ANALYZE for slow queries by default
     end
 
     def resolve_api_key
@@ -104,6 +108,12 @@ module ApmBro
       list.any? { |pat| match_name_or_pattern?(job_class_name, pat) }
     end
 
+    def exclusive_job?(job_class_name)
+      list = resolve_exclusive_jobs
+      return true if list.nil? || list.empty? # If not defined, allow all (default behavior)
+      list.any? { |pat| match_name_or_pattern?(job_class_name, pat) }
+    end
+
     def excluded_controller_action?(controller_name, action_name)
       list = resolve_excluded_controller_actions
       return false if list.nil? || list.empty?
@@ -111,16 +121,53 @@ module ApmBro
       list.any? { |pat| match_name_or_pattern?(target, pat) }
     end
 
+    def exclusive_controller_action?(controller_name, action_name)
+      list = resolve_exclusive_controller_actions
+      return true if list.nil? || list.empty? # If not defined, allow all (default behavior)
+      target = "#{controller_name}##{action_name}"
+      list.any? { |pat| match_name_or_pattern?(target, pat) }
+    end
+
     def resolve_excluded_controller_actions
-      return @excluded_controller_actions if @excluded_controller_actions && !@excluded_controller_actions.empty?
+      # Collect patterns from @excluded_controller_actions
+      patterns = []
+      if @excluded_controller_actions && !@excluded_controller_actions.empty?
+        patterns.concat(Array(@excluded_controller_actions))
+      end
+
+      # Also check @excluded_controllers for patterns containing '#' (controller action patterns)
+      if @excluded_controllers && !@excluded_controllers.empty?
+        action_patterns = Array(@excluded_controllers).select { |pat| pat.to_s.include?("#") }
+        patterns.concat(action_patterns)
+      end
+
+      return patterns if !patterns.empty?
 
       if defined?(Rails)
         list = fetch_from_rails_settings(%w[apm_bro excluded_controller_actions])
-        return Array(list) if list
+        if list
+          rails_patterns = Array(list)
+          # Also check excluded_controllers from Rails settings for action patterns
+          controllers_list = fetch_from_rails_settings(%w[apm_bro excluded_controllers])
+          if controllers_list
+            action_patterns = Array(controllers_list).select { |pat| pat.to_s.include?("#") }
+            rails_patterns.concat(action_patterns)
+          end
+          return rails_patterns if !rails_patterns.empty?
+        end
       end
 
       env = ENV["APM_BRO_EXCLUDED_CONTROLLER_ACTIONS"]
-      return env.split(",").map(&:strip) if env && !env.strip.empty?
+      if env && !env.strip.empty?
+        env_patterns = env.split(",").map(&:strip)
+        # Also check excluded_controllers env var for action patterns
+        controllers_env = ENV["APM_BRO_EXCLUDED_CONTROLLERS"]
+        if controllers_env && !controllers_env.strip.empty?
+          action_patterns = controllers_env.split(",").map(&:strip).select { |pat| pat.include?("#") }
+          env_patterns.concat(action_patterns)
+        end
+        return env_patterns if !env_patterns.empty?
+      end
 
       []
     end
@@ -153,6 +200,58 @@ module ApmBro
       []
     end
 
+    def resolve_exclusive_controller_actions
+      # Collect patterns from @exclusive_controller_actions
+      patterns = []
+      if @exclusive_controller_actions && !@exclusive_controller_actions.empty?
+        patterns.concat(Array(@exclusive_controller_actions))
+      end
+
+      return patterns if !patterns.empty?
+
+      if defined?(Rails)
+        list = fetch_from_rails_settings(%w[apm_bro exclusive_controller_actions])
+        if list
+          rails_patterns = Array(list)
+          return rails_patterns if !rails_patterns.empty?
+        end
+      end
+
+      env = ENV["APM_BRO_EXCLUSIVE_CONTROLLER_ACTIONS"]
+      if env && !env.strip.empty?
+        env_patterns = env.split(",").map(&:strip)
+        return env_patterns if !env_patterns.empty?
+      end
+
+      []
+    end
+
+    def resolve_exclusive_jobs
+      # Collect patterns from @exclusive_jobs
+      patterns = []
+      if @exclusive_jobs && !@exclusive_jobs.empty?
+        patterns.concat(Array(@exclusive_jobs))
+      end
+
+      return patterns if !patterns.empty?
+
+      if defined?(Rails)
+        list = fetch_from_rails_settings(%w[apm_bro exclusive_jobs])
+        if list
+          rails_patterns = Array(list)
+          return rails_patterns if !rails_patterns.empty?
+        end
+      end
+
+      env = ENV["APM_BRO_EXCLUSIVE_JOBS"]
+      if env && !env.strip.empty?
+        env_patterns = env.split(",").map(&:strip)
+        return env_patterns if !env_patterns.empty?
+      end
+
+      []
+    end
+
     def should_sample?
       sample_rate = resolve_sample_rate
       return true if sample_rate >= 100
@@ -186,8 +285,16 @@ module ApmBro
       return false if name.nil? || pattern.nil?
       pat = pattern.to_s
       return !!(name.to_s == pat) unless pat.include?("*")
-      # Convert simple wildcard pattern (e.g., "Admin::*") to regex
-      regex = Regexp.new("^" + Regexp.escape(pat).gsub("\\*", "[^:]*") + "$")
+      
+      # For controller action patterns (containing '#'), use .* to match any characters including colons
+      # For controller-only patterns, use [^:]* to match namespace segments
+      if pat.include?("#")
+        # Controller action pattern: allow * to match any characters including colons
+        regex = Regexp.new("^" + Regexp.escape(pat).gsub("\\*", ".*") + "$")
+      else
+        # Controller-only pattern: use [^:]* to match namespace segments
+        regex = Regexp.new("^" + Regexp.escape(pat).gsub("\\*", "[^:]*") + "$")
+      end
       !!(name.to_s =~ regex)
     rescue
       false

data/lib/apm_bro/job_subscriber.rb

@@ -19,6 +19,10 @@ module ApmBro
           if ApmBro.configuration.excluded_job?(job_class_name)
             next
           end
+          # If exclusive_jobs is defined and not empty, only track matching jobs
+          unless ApmBro.configuration.exclusive_job?(job_class_name)
+            next
+          end
         rescue
         end
 
@@ -82,6 +86,10 @@ module ApmBro
           if ApmBro.configuration.excluded_job?(job_class_name)
             next
           end
+          # If exclusive_jobs is defined and not empty, only track matching jobs
+          unless ApmBro.configuration.exclusive_job?(job_class_name)
+            next
+          end
         rescue
         end
 

data/lib/apm_bro/sql_subscriber.rb

@@ -13,6 +13,7 @@ module ApmBro
     THREAD_LOCAL_ALLOC_START_KEY = :apm_bro_sql_alloc_start
     THREAD_LOCAL_ALLOC_RESULTS_KEY = :apm_bro_sql_alloc_results
     THREAD_LOCAL_BACKTRACE_KEY = :apm_bro_sql_backtraces
+    THREAD_LOCAL_EXPLAIN_PENDING_KEY = :apm_bro_explain_pending
 
     def self.subscribe!
       # Subscribe with a start/finish listener to measure allocations per query
@@ -40,15 +41,26 @@ module ApmBro
         rescue
         end
 
+        duration_ms = ((finished - started) * 1000.0).round(2)
+        original_sql = data[:sql]
+
         query_info = {
-          sql: sanitize_sql(data[:sql]),
+          sql: sanitize_sql(original_sql),
           name: data[:name],
-          duration_ms: ((finished - started) * 1000.0).round(2),
+          duration_ms: duration_ms,
           cached: data[:cached] || false,
           connection_id: data[:connection_id],
           trace: safe_query_trace(data, captured_backtrace),
           allocations: allocations
         }
+
+        # Run EXPLAIN ANALYZE for slow queries in the background
+        if should_explain_query?(duration_ms, original_sql)
+          # Store reference to query_info so we can update it when EXPLAIN completes
+          query_info[:explain_plan] = nil # Placeholder
+          start_explain_analyze_background(original_sql, data[:connection_id], query_info)
+        end
+
         # Add to thread-local storage
         Thread.current[THREAD_LOCAL_KEY] << query_info
       end
@@ -59,17 +71,43 @@ module ApmBro
       Thread.current[THREAD_LOCAL_ALLOC_START_KEY] = {}
       Thread.current[THREAD_LOCAL_ALLOC_RESULTS_KEY] = {}
       Thread.current[THREAD_LOCAL_BACKTRACE_KEY] = {}
+      Thread.current[THREAD_LOCAL_EXPLAIN_PENDING_KEY] = []
     end
 
     def self.stop_request_tracking
+      # Wait for any pending EXPLAIN ANALYZE queries to complete (with timeout)
+      # This must happen BEFORE we get the queries array reference to ensure
+      # all explain_plan fields are populated
+      wait_for_pending_explains(5.0) # 5 second timeout
+      
+      # Get queries after waiting for EXPLAIN to complete
       queries = Thread.current[THREAD_LOCAL_KEY]
+      
       Thread.current[THREAD_LOCAL_KEY] = nil
       Thread.current[THREAD_LOCAL_ALLOC_START_KEY] = nil
       Thread.current[THREAD_LOCAL_ALLOC_RESULTS_KEY] = nil
       Thread.current[THREAD_LOCAL_BACKTRACE_KEY] = nil
+      Thread.current[THREAD_LOCAL_EXPLAIN_PENDING_KEY] = nil
       queries || []
     end
 
+    def self.wait_for_pending_explains(timeout_seconds)
+      pending = Thread.current[THREAD_LOCAL_EXPLAIN_PENDING_KEY]
+      return unless pending && !pending.empty?
+      
+      start_time = Time.now
+      pending.each do |thread|
+        remaining_time = timeout_seconds - (Time.now - start_time)
+        break if remaining_time <= 0
+        
+        begin
+          thread.join(remaining_time)
+        rescue => e
+          ApmBro.logger.debug("Error waiting for EXPLAIN ANALYZE: #{e.message}")
+        end
+      end
+    end
+
     def self.sanitize_sql(sql)
       return sql unless sql.is_a?(String)
 
@@ -86,6 +124,215 @@ module ApmBro
       (sql.length > 1000) ? sql[0..1000] + "..." : sql
     end
 
+    def self.should_explain_query?(duration_ms, sql)
+      return false unless ApmBro.configuration.explain_analyze_enabled
+      return false if duration_ms < ApmBro.configuration.slow_query_threshold_ms
+      return false unless sql.is_a?(String)
+      return false if sql.strip.empty?
+      
+      # Skip EXPLAIN for certain query types that don't benefit from it
+      sql_upper = sql.upcase.strip
+      return false if sql_upper.start_with?("EXPLAIN")
+      return false if sql_upper.start_with?("BEGIN")
+      return false if sql_upper.start_with?("COMMIT")
+      return false if sql_upper.start_with?("ROLLBACK")
+      return false if sql_upper.start_with?("SAVEPOINT")
+      return false if sql_upper.start_with?("RELEASE")
+      
+      true
+    end
+
+    def self.start_explain_analyze_background(sql, connection_id, query_info)
+      return unless defined?(ActiveRecord)
+      return unless ActiveRecord::Base.respond_to?(:connection)
+      
+      # Capture the main thread reference to append logs to the correct thread
+      main_thread = Thread.current
+      
+      # Run EXPLAIN in a background thread to avoid blocking the main request
+      explain_thread = Thread.new do
+        connection = nil
+        begin
+          # Use a separate connection to avoid interfering with the main query
+          if ActiveRecord::Base.connection_pool.respond_to?(:checkout)
+            connection = ActiveRecord::Base.connection_pool.checkout
+          else
+            connection = ActiveRecord::Base.connection
+          end
+          
+          # Build EXPLAIN query based on database adapter
+          explain_sql = build_explain_query(sql, connection)
+          
+          # Execute the EXPLAIN query
+          # For PostgreSQL, use select_all which returns ActiveRecord::Result
+          # For other databases, use execute
+          adapter_name = connection.adapter_name.downcase
+          if adapter_name == "postgresql" || adapter_name == "postgis"
+            # PostgreSQL: select_all returns ActiveRecord::Result with rows
+            result = connection.select_all(explain_sql)
+          else
+            # Other databases: use execute
+            result = connection.execute(explain_sql)
+          end
+          
+          # Format the result based on database adapter
+          explain_plan = format_explain_result(result, connection)
+          
+          # Update the query_info with the explain plan
+          # This updates the hash that's already in the queries array
+          if explain_plan && !explain_plan.to_s.strip.empty?
+            query_info[:explain_plan] = explain_plan
+            append_log_to_thread(main_thread, :debug, "Captured EXPLAIN ANALYZE for slow query (#{query_info[:duration_ms]}ms): #{explain_plan[0..1000]}...")
+          else
+            query_info[:explain_plan] = nil
+            append_log_to_thread(main_thread, :debug, "EXPLAIN ANALYZE returned empty result. Result type: #{result.class}, Result: #{result.inspect[0..200]}")
+          end
+        rescue => e
+          # Silently fail - don't let EXPLAIN break the application
+          append_log_to_thread(main_thread, :debug, "Failed to capture EXPLAIN ANALYZE: #{e.message}")
+          query_info[:explain_plan] = nil
+        ensure
+          # Return connection to pool if we checked it out
+          if connection && ActiveRecord::Base.connection_pool.respond_to?(:checkin)
+            ActiveRecord::Base.connection_pool.checkin(connection) rescue nil
+          end
+        end
+      end
+      
+      # Track the thread so we can wait for it when stopping request tracking
+      pending = Thread.current[THREAD_LOCAL_EXPLAIN_PENDING_KEY] ||= []
+      pending << explain_thread
+    rescue => e
+      # Use ApmBro.logger here since we're still in the main thread
+      ApmBro.logger.debug("Failed to start EXPLAIN ANALYZE thread: #{e.message}")
+    end
+
+    # Append a log entry directly to a specific thread's log storage
+    # This is used when logging from background threads to ensure logs
+    # are collected with the main request thread's logs
+    def self.append_log_to_thread(thread, severity, message)
+      timestamp = Time.now.utc
+      log_entry = {
+        sev: severity.to_s,
+        msg: message.to_s,
+        time: timestamp.iso8601(3)
+      }
+
+      # Append to the specified thread's log storage
+      thread[:apm_bro_logs] ||= []
+      thread[:apm_bro_logs] << log_entry
+
+      # Also print the message immediately (using current thread's logger)
+      begin
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          formatted_message = "[ApmBro] #{timestamp.iso8601(3)} #{severity.to_s.upcase}: #{message}"
+          case severity
+          when :debug
+            Rails.logger.debug(formatted_message)
+          when :info
+            Rails.logger.info(formatted_message)
+          when :warn
+            Rails.logger.warn(formatted_message)
+          when :error
+            Rails.logger.error(formatted_message)
+          when :fatal
+            Rails.logger.fatal(formatted_message)
+          end
+        else
+          # Fallback to stdout
+          $stdout.puts("[ApmBro] #{timestamp.iso8601(3)} #{severity.to_s.upcase}: #{message}")
+        end
+      rescue
+        # Never let logging break the application
+        $stdout.puts("[ApmBro] #{severity.to_s.upcase}: #{message}")
+      end
+    end
+
+    def self.build_explain_query(sql, connection)
+      adapter_name = connection.adapter_name.downcase
+      
+      case adapter_name
+      when "postgresql", "postgis"
+        # PostgreSQL supports ANALYZE and BUFFERS
+        "EXPLAIN (ANALYZE, BUFFERS) #{sql}"
+      when "mysql", "mysql2", "trilogy"
+        # MySQL uses different syntax - ANALYZE is a separate keyword
+        "EXPLAIN ANALYZE #{sql}"
+      when "sqlite3"
+        # SQLite supports EXPLAIN QUERY PLAN
+        "EXPLAIN QUERY PLAN #{sql}"
+      else
+        # Generic fallback - just EXPLAIN
+        "EXPLAIN #{sql}"
+      end
+    end
+
+    def self.format_explain_result(result, connection)
+      adapter_name = connection.adapter_name.downcase
+      
+      case adapter_name
+      when "postgresql", "postgis"
+        # PostgreSQL returns ActiveRecord::Result from select_all
+        if result.respond_to?(:rows)
+          # ActiveRecord::Result object - rows is an array of arrays
+          # Each row is [query_plan_string]
+          plan_text = result.rows.map { |row| row.is_a?(Array) ? row.first.to_s : row.to_s }.join("\n")
+          return plan_text unless plan_text.strip.empty?
+        end
+        
+        # Try alternative methods to extract the plan
+        if result.respond_to?(:each) && result.respond_to?(:columns)
+          # ActiveRecord::Result with columns
+          plan_column = result.columns.find { |col| col.downcase.include?("plan") || col.downcase.include?("query") } || result.columns.first
+          plan_text = result.map { |row| 
+            if row.is_a?(Hash)
+              row[plan_column] || row[plan_column.to_sym] || row.values.first
+            else
+              row
+            end
+          }.join("\n")
+          return plan_text unless plan_text.strip.empty?
+        end
+        
+        if result.is_a?(Array)
+          # Array of hashes or arrays
+          plan_text = result.map do |row|
+            if row.is_a?(Hash)
+              row["QUERY PLAN"] || row["query plan"] || row[:query_plan] || row.values.first.to_s
+            elsif row.is_a?(Array)
+              row.first.to_s
+            else
+              row.to_s
+            end
+          end.join("\n")
+          return plan_text unless plan_text.strip.empty?
+        end
+        
+        # Fallback to string representation
+        result.to_s
+      when "mysql", "mysql2", "trilogy"
+        # MySQL returns rows
+        if result.is_a?(Array)
+          result.map { |row| row.is_a?(Hash) ? row.values.join(" | ") : row.to_s }.join("\n")
+        else
+          result.to_s
+        end
+      when "sqlite3"
+        # SQLite returns rows
+        if result.is_a?(Array)
+          result.map { |row| row.is_a?(Hash) ? row.values.join(" | ") : row.to_s }.join("\n")
+        else
+          result.to_s
+        end
+      else
+        # Generic fallback
+        result.to_s
+      end
+    rescue => e
+      # Fallback to string representation
+      result.to_s
+    end
+
     def self.safe_query_trace(data, captured_backtrace = nil)
       return [] unless data.is_a?(Hash)
 

data/lib/apm_bro/subscriber.rb

@@ -9,12 +9,17 @@ module ApmBro
     def self.subscribe!(client: Client.new)
       ActiveSupport::Notifications.subscribe(EVENT_NAME) do |name, started, finished, _unique_id, data|
         # Skip excluded controllers or controller#action pairs
+        # Also check exclusive_controller_actions - if defined, only track those
         begin
           controller_name = data[:controller].to_s
           action_name = data[:action].to_s
           if ApmBro.configuration.excluded_controller_action?(controller_name, action_name)
             next
           end
+          # If exclusive_controller_actions is defined and not empty, only track matching actions
+          unless ApmBro.configuration.exclusive_controller_action?(controller_name, action_name)
+            next
+          end
         rescue
         end
 

data/lib/apm_bro/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApmBro
-  VERSION = "0.1.15"
+  VERSION = "0.1.17"
 end

data/lib/apm_bro.rb

@@ -51,4 +51,13 @@ module ApmBro
   def self.logger
     @logger ||= Logger.new
   end
+
+  # Returns the current environment (Rails.env or ENV fallback)
+  def self.env
+    if defined?(Rails) && Rails.respond_to?(:env)
+      Rails.env
+    else
+      ENV["RACK_ENV"] || ENV["RAILS_ENV"] || "development"
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: apm_bro
 version: !ruby/object:Gem::Version
-  version: 0.1.15
+  version: 0.1.17
 platform: ruby
 authors:
 - Emanuel Comsa
@@ -18,6 +18,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- FEATURES.md
 - README.md
 - lib/apm_bro.rb
 - lib/apm_bro/cache_subscriber.rb