dead_bro 0.2.23 → 0.2.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d17b4a0fa119f9917bfdf77cc66078019bf72e87ca5c2752183b9e3b85629f5
-  data.tar.gz: 26bec0d029e000bd2ecff843ca242b8647862bf39727b31cef6408baa871cd13
+  metadata.gz: 2123fe4aad1331c3a33afdf2e5f9cffcfac75f5893982522569da053fc4ea403
+  data.tar.gz: a00a450442279e95799fb6ddd3e2d55b4b18e8ed26926f55c09ea076f12d02eb
 SHA512:
-  metadata.gz: 97c4aba35a1f39c680d8445a9a31dc3ae35d9e0ea29b89eee0f3f9740086db8de498b810d7e38171665106d9f8ff3d15caaef47cbc257c6d39bea31da2852d64
-  data.tar.gz: 321aee532718f23c430a81fdec50ab3d27fe5373e02fab0f1598e884d3d0d02b10d175691d1ec08d0bffde97a0cbb5e7488d1b0125d29b6552009921c2dba4e2
+  metadata.gz: ba0645dca3b3552e6c8b4aaef11e8f008e7822ba5d67ff9b8133c05bfe21b0a719252f655f7a893e99369aafe4c6e2ac3c886a372bc353b48c044d22b83d7f36
+  data.tar.gz: dffa7888b43a8642fb9ee32ec9334f8cb13dab4c176353171a533780d086eca99257198e0f9a4d0609cc6897a5d51a7591213da3442929c82b2bdf00aa65d738

data/README.md

@@ -14,13 +14,21 @@ Add to your Gemfile:
 gem "dead_bro", git: "https://github.com/rubydevro/dead_bro.git"
 ```
 
+Then run the install generator to create the initializer:
+
+```sh
+bin/rails generate dead_bro:install
+```
+
+This creates `config/initializers/dead_bro.rb`. Set `DEAD_BRO_API_KEY` in your environment and you're done.
+
 ## Usage
 
 By default, if Rails is present, DeadBro auto-subscribes to `process_action.action_controller` and posts metrics asynchronously.
 
 ### 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:
+The install generator above creates `config/initializers/dead_bro.rb` for you. If you prefer to add it manually, create the file 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|

data/lib/dead_bro/job_subscriber.rb

@@ -105,6 +105,7 @@ module DeadBro
           job_id: data[:job].job_id,
           queue_name: data[:job].queue_name,
           arguments: safe_arguments(data[:job].arguments),
+          started_at: started.utc.iso8601(3),
           duration_ms: duration_ms,
           queue_duration_ms: queue_duration_ms,
           db_connection_wait_ms: db_connection_stats[:wait_ms],
@@ -201,6 +202,7 @@ module DeadBro
           job_id: data[:job].job_id,
           queue_name: data[:job].queue_name,
           arguments: safe_arguments(data[:job].arguments),
+          started_at: started.utc.iso8601(3),
           duration_ms: duration_ms,
           queue_duration_ms: queue_duration_ms,
           db_connection_wait_ms: db_connection_stats[:wait_ms],

data/lib/dead_bro/subscriber.rb

@@ -165,6 +165,7 @@ module DeadBro
           method: data[:method],
           path: safe_path(data),
           status: data[:status],
+          started_at: started.utc.iso8601(3),
           duration_ms: duration_ms,
           view_runtime_ms: data[:view_runtime],
           db_runtime_ms: data[:db_runtime],

data/lib/dead_bro/version.rb

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

data/lib/generators/dead_bro/install/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module DeadBro
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a DeadBro initializer in config/initializers/dead_bro.rb"
+
+      def create_initializer
+        template "dead_bro.rb", "config/initializers/dead_bro.rb"
+      end
+    end
+  end
+end

data/lib/generators/dead_bro/install/templates/dead_bro.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+DeadBro.configure do |cfg|
+  cfg.api_key = ENV["DEAD_BRO_API_KEY"]
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dead_bro
 version: !ruby/object:Gem::Version
-  version: 0.2.23
+  version: 0.2.24
 platform: ruby
 authors:
 - Emanuel Comsa
@@ -18,7 +18,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- FEATURES.md
 - README.md
 - lib/dead_bro.rb
 - lib/dead_bro/ar_object_tracker.rb
@@ -57,6 +56,8 @@ files:
 - lib/dead_bro/subscriber.rb
 - lib/dead_bro/version.rb
 - lib/dead_bro/view_rendering_subscriber.rb
+- lib/generators/dead_bro/install/install_generator.rb
+- lib/generators/dead_bro/install/templates/dead_bro.rb
 homepage: https://www.deadbro.com
 licenses: []
 metadata:
@@ -76,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Minimal APM for Rails apps.
 test_files: []

data/FEATURES.md

@@ -1,333 +0,0 @@
-# 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 (`Configuration#deploy_id=` wins when set, then ENV in `Configuration::DEPLOY_REVISION_ENV_KEYS` order—including `DEAD_BRO_DEPLOY_ID`, git/CI vars, `DD_VERSION`, etc.), otherwise a **per-process UUID** (fine for single dyno/process; unusable alone for fleets like ECS replicas)
-- **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
-