apm_bro 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f5e04ee9c91623872f5d3b5ee06f99ea4acb4da38f99efc9048d2e61a674723
-  data.tar.gz: dae5536d6035f67546136f12ffe1fc52d602bdffc8dd5eeba120fec2313c4cd7
+  metadata.gz: 1763fe75b6723866fbf061cdc8a978105e3a8bd1be612c2dc0937865c576a1da
+  data.tar.gz: e1bad4ee3231e2a0783994983986e040cec36314912e30f402c044a41f47bdea
 SHA512:
-  metadata.gz: e7df9304f1d6ab9be869b9856648e67382623bec5ce59d727de9e5490234d95c1f10c857e924fea02977810dbdc387564b3790d96bb68f3de680980d6e6a92b4
-  data.tar.gz: 8cf8d948c812075b068479e25737a0d43999831f2dea87a018d6d62fe8c1049d96bb27076f88173ed91d4bd4ae1939669d768402ee9e8ce8e5c215c14014d909
+  metadata.gz: 070b54479382d040aebd53e2927d0ebd0aff1a0e0e3a8b4ad4045cc674cec680fd64f2cb279c18412aeff347a34eb098de6bb4fcf227094d2a11e61c12b33b67
+  data.tar.gz: 17894ab0bb4446d2fb90848ee0f1996683390710e6f81c198fa357f31822a6577fae98b70749feb46f1e2fbba70e71dd38bbb4886252114164b5d8dcac96a652

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-08-28
+
+- Initial release

data/README.md

@@ -0,0 +1,211 @@
+# ApmBro (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.
+
+To use the gem you need to have a free account with [DeadBro - Rails APM](https://www.deadbro.com)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "apm_bro", git: "https://github.com/rubydevro/apm_bro.git"
+```
+
+## Usage
+
+By default, if Rails is present, ApmBro auto-subscribes to `process_action.action_controller` and posts metrics asynchronously.
+
+### Configuration settings
+
+You can set via an initializer:
+
+
+```ruby
+ApmBro.configure do |cfg|
+  cfg.api_key = ENV["APM_BRO_API_KEY"]
+  cfg.enabled = true
+end
+```
+
+## User Email Tracking
+
+ApmBro can track the email of the user making requests, which is useful for debugging user-specific issues and understanding user behavior patterns.
+
+### Configuration
+
+Enable user email tracking in your Rails configuration:
+
+```ruby
+# In config/application.rb or environments/*.rb
+ApmBro.configure do |config|
+  config.user_email_tracking_enabled = true
+end
+```
+
+### Default Email Extraction
+
+By default, ApmBro will try to extract user email from these sources (in order of priority):
+
+1. **`current_user.email`** - Most common in Rails apps with authentication
+2. **Request parameters** - `user_email` or `email` in params
+3. **HTTP headers** - `X-User-Email` or `HTTP_X_USER_EMAIL`
+4. **Session data** - `user_email` in session
+
+### Custom Email Extractor
+
+In progress
+
+### Security Considerations
+
+- User email tracking is **disabled by default** for privacy
+- Only enable when necessary for debugging or analytics
+- Consider your data privacy requirements and regulations
+- The email is included in all request payloads sent to our APM endpoint
+
+## Request Sampling
+
+ApmBro supports configurable request sampling to reduce the volume of metrics sent to your APM endpoint, which is useful for high-traffic applications.
+
+### Configuration
+
+Set the sample rate as a percentage (1-100):
+
+```ruby
+# Track 50% of requests
+ApmBro.configure do |config|
+  config.sample_rate = 50
+end
+
+# Track 10% of requests (useful for high-traffic apps)
+ApmBro.configure do |config|
+  config.sample_rate = 10
+end
+
+# Track all requests (default)
+ApmBro.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.
+
+### Configuration
+
+
+```ruby
+ApmBro.configure do |config|
+  config.excluded_controllers = [
+    "HealthChecksController",
+    "Admin::*" # wildcard supported
+  ]
+
+  config.excluded_controller_actions = [
+    "UsersController#show",
+    "Admin::ReportsController#index",
+    "Admin::*#*" # wildcard supported for controller and action
+  ]
+
+  config.excluded_jobs = [
+    "ActiveStorage::AnalyzeJob",
+    "Admin::*"
+  ]
+end
+```
+
+Notes:
+- Wildcards `*` are supported for controller and action (e.g., `Admin::*#*`).
+- Matching is done against full names like `UsersController`, `Admin::ReportsController#index`, `MyJob`.
+
+## SQL Query Tracking
+
+ApmBro automatically tracks SQL queries executed during each request and job. Each request will include a `sql_queries` array containing:
+- `sql` - The SQL query (always sanitized)
+- `name` - Query name (e.g., "User Load", "User Update")
+- `duration_ms` - Query execution time in milliseconds
+- `cached` - Whether the query was cached
+- `connection_id` - Database connection ID
+- `trace` - Call stack showing where the query was executed
+
+## View Rendering Tracking
+
+ApmBro automatically tracks view rendering performance for each request. This includes:
+
+- **Individual view events**: Templates, partials, and collections rendered
+- **Performance metrics**: Rendering times for each view component
+- **Cache analysis**: Cache hit rates for partials and collections
+- **Slow view detection**: Identification of the slowest rendering views
+- **Frequency analysis**: Most frequently rendered views
+
+## Memory Tracking & Leak Detection
+
+ApmBro automatically tracks memory usage and detects memory leaks with minimal performance impact. This includes:
+
+### Performance-Optimized Memory Tracking
+
+By default, ApmBro uses **lightweight memory tracking** that has minimal performance impact:
+
+- **Memory Usage Monitoring**: Track memory consumption per request (using GC stats, not system calls)
+- **Memory Leak Detection**: Detect growing memory patterns over time
+- **GC Efficiency Analysis**: Monitor garbage collection effectiveness
+- **Zero Allocation Tracking**: No object allocation tracking by default (can be enabled)
+
+### Configuration Options
+
+```ruby
+# In your Rails configuration
+ApmBro.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)
+  
+  # Sampling configuration
+  config.sample_rate = 100                     # Percentage of requests to track (1-100, default: 100)
+end
+```
+
+**Performance Impact:**
+- **Lightweight mode**: ~0.1ms overhead per request
+- **Allocation tracking**: ~2-5ms overhead per request (only enable when needed)
+
+## Job Tracking
+
+ApmBro automatically tracks ActiveJob background jobs when ActiveJob is available. Each job execution is tracked with:
+
+- `job_class` - The job class name (e.g., "UserMailer::WelcomeEmail")
+- `job_id` - Unique job identifier
+- `queue_name` - The queue the job was processed from
+- `arguments` - Sanitized job arguments (sensitive data filtered)
+- `duration_ms` - Job execution time in milliseconds
+- `status` - "completed" or "failed"
+- `sql_queries` - Array of SQL queries executed during the job
+- `exception_class` - Exception class name (for failed jobs)
+- `message` - Exception message (for failed jobs)
+- `backtrace` - Exception backtrace (for failed jobs)
+
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rubydevro/apm_bro.

data/lib/apm_bro/cache_subscriber.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module ApmBro
+  class CacheSubscriber
+    THREAD_LOCAL_KEY = :apm_bro_cache_events
+
+    EVENTS = [
+      "cache_read.active_support",
+      "cache_write.active_support",
+      "cache_delete.active_support",
+      "cache_exist?.active_support",
+      "cache_fetch_hit.active_support",
+      "cache_generate.active_support",
+      "cache_read_multi.active_support",
+      "cache_write_multi.active_support"
+    ].freeze
+
+    def self.subscribe!
+      EVENTS.each do |event_name|
+        begin
+          ActiveSupport::Notifications.subscribe(event_name) do |name, started, finished, _unique_id, data|
+            next unless Thread.current[THREAD_LOCAL_KEY]
+
+            duration_ms = ((finished - started) * 1000.0).round(2)
+            event = build_event(name, data, duration_ms)
+            Thread.current[THREAD_LOCAL_KEY] << event if event
+          end
+        rescue StandardError
+        end
+      end
+    rescue StandardError
+      # Never raise from instrumentation install
+    end
+
+    def self.start_request_tracking
+      Thread.current[THREAD_LOCAL_KEY] = []
+    end
+
+    def self.stop_request_tracking
+      events = Thread.current[THREAD_LOCAL_KEY]
+      Thread.current[THREAD_LOCAL_KEY] = nil
+      events || []
+    end
+
+    def self.build_event(name, data, duration_ms)
+      return nil unless data.is_a?(Hash)
+
+      base = {
+        event: name,
+        duration_ms: duration_ms,
+        key: safe_key(data[:key]),
+        keys_count: safe_keys_count(data[:keys]),
+        hit: infer_hit(name, data),
+        store: safe_store_name(data[:store]),
+        namespace: safe_namespace(data[:namespace]),
+        at: Time.now.utc.to_i
+      }
+
+      base
+    rescue StandardError
+      nil
+    end
+
+    def self.safe_key(key)
+      return nil if key.nil?
+      s = key.to_s
+      s.length > 200 ? s[0, 200] + "…" : s
+    rescue StandardError
+      nil
+    end
+
+    def self.safe_keys_count(keys)
+      if keys.respond_to?(:size)
+        keys.size
+      else
+        nil
+      end
+    rescue StandardError
+      nil
+    end
+
+    def self.safe_store_name(store)
+      return nil unless store
+      if store.respond_to?(:name)
+        store.name
+      else
+        store.class.name
+      end
+    rescue StandardError
+      nil
+    end
+
+    def self.safe_namespace(ns)
+      ns.to_s[0, 100]
+    rescue StandardError
+      nil
+    end
+
+    def self.infer_hit(name, data)
+      case name
+      when "cache_fetch_hit.active_support"
+        true
+      when "cache_read.active_support"
+        !!data[:hit]
+      else
+        nil
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end
+
+

data/lib/apm_bro/circuit_breaker.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module ApmBro
+  class CircuitBreaker
+    # Circuit breaker states
+    CLOSED = :closed
+    OPEN = :open
+    HALF_OPEN = :half_open
+
+    # Default configuration
+    DEFAULT_FAILURE_THRESHOLD = 3
+    DEFAULT_RECOVERY_TIMEOUT = 60 # seconds
+    DEFAULT_RETRY_TIMEOUT = 300 # seconds for retry attempts
+
+    def initialize(
+      failure_threshold: DEFAULT_FAILURE_THRESHOLD,
+      recovery_timeout: DEFAULT_RECOVERY_TIMEOUT,
+      retry_timeout: DEFAULT_RETRY_TIMEOUT
+    )
+      @failure_threshold = failure_threshold
+      @recovery_timeout = recovery_timeout
+      @retry_timeout = retry_timeout
+      
+      @state = CLOSED
+      @failure_count = 0
+      @last_failure_time = nil
+      @last_success_time = nil
+    end
+
+    def call(&block)
+      case @state
+      when CLOSED
+        execute_with_monitoring(&block)
+      when OPEN
+        if should_attempt_reset?
+          @state = HALF_OPEN
+          execute_with_monitoring(&block)
+        else
+          :circuit_open
+        end
+      when HALF_OPEN
+        execute_with_monitoring(&block)
+      end
+    end
+
+    def state
+      @state
+    end
+
+    def failure_count
+      @failure_count
+    end
+
+    def last_failure_time
+      @last_failure_time
+    end
+
+    def last_success_time
+      @last_success_time
+    end
+
+    def reset!
+      @state = CLOSED
+      @failure_count = 0
+      @last_failure_time = nil
+    end
+
+    def open!
+      @state = OPEN
+      @last_failure_time = Time.now
+    end
+
+    def transition_to_half_open!
+      @state = HALF_OPEN
+    end
+
+    def should_attempt_reset?
+      return false unless @last_failure_time
+      
+      # Try to reset after recovery timeout
+      elapsed = Time.now - @last_failure_time
+      elapsed >= @recovery_timeout
+    end
+
+    private
+
+    def execute_with_monitoring(&block)
+      result = block.call
+      
+      if success?(result)
+        on_success
+        result
+      else
+        on_failure
+        result
+      end
+    rescue StandardError => e
+      on_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

data/lib/apm_bro/client.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "timeout"
+
+module ApmBro
+  class Client
+    def initialize(configuration = ApmBro.configuration)
+      @configuration = configuration
+      @circuit_breaker = create_circuit_breaker
+    end
+
+    def post_metric(event_name:, payload:)
+      unless @configuration.enabled
+        return
+      end
+
+      # Check sampling rate - skip if not selected for sampling
+      unless @configuration.should_sample?
+        return
+      end
+
+      api_key = @configuration.resolve_api_key
+      
+      if api_key.nil?
+        return
+      end
+
+      # Check circuit breaker before making request
+      if @circuit_breaker && @configuration.circuit_breaker_enabled
+        if @circuit_breaker.state == :open
+          # Check if we should attempt a reset to half-open state
+          if @circuit_breaker.should_attempt_reset?
+            @circuit_breaker.transition_to_half_open!
+          else
+            return
+          end
+        end
+      end
+
+      # Make the HTTP request (async)
+      make_http_request(event_name, payload, api_key)
+
+      nil
+    end
+
+    private
+
+    def create_circuit_breaker
+      return nil unless @configuration.circuit_breaker_enabled
+      
+      CircuitBreaker.new(
+        failure_threshold: @configuration.circuit_breaker_failure_threshold,
+        recovery_timeout: @configuration.circuit_breaker_recovery_timeout,
+        retry_timeout: @configuration.circuit_breaker_retry_timeout
+      )
+    end
+
+    def make_http_request(event_name, payload, api_key)
+      endpoint_url = @configuration.respond_to?(:ruby_dev) && @configuration.ruby_dev ?
+          'http://localhost:3100/apm/v1/metrics' :
+          "https://www.deadbro.com/apm/v1/metrics"
+
+      uri = URI.parse(endpoint_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @configuration.open_timeout
+      http.read_timeout = @configuration.read_timeout
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{api_key}"
+      body = { event: event_name, payload: payload, sent_at: Time.now.utc.iso8601, revision: @configuration.resolve_deploy_id }
+      request.body = JSON.dump(body)
+
+      # Fire-and-forget using a short-lived thread to avoid blocking the request cycle.
+      Thread.new do
+        begin
+          response = http.request(request)
+
+          if response
+            # Update circuit breaker based on response
+            if @circuit_breaker && @configuration.circuit_breaker_enabled
+              if response.is_a?(Net::HTTPSuccess)
+                @circuit_breaker.send(:on_success)
+              else
+                @circuit_breaker.send(:on_failure)
+              end
+            end
+          else
+            # Treat nil response as failure for circuit breaker
+            if @circuit_breaker && @configuration.circuit_breaker_enabled
+              @circuit_breaker.send(:on_failure)
+            end
+          end
+          
+          response
+        rescue Timeout::Error => e
+          
+          # Update circuit breaker on timeout
+          if @circuit_breaker && @configuration.circuit_breaker_enabled
+            @circuit_breaker.send(:on_failure)
+          end
+        rescue StandardError => e
+          
+          # Update circuit breaker on exception
+          if @circuit_breaker && @configuration.circuit_breaker_enabled
+            @circuit_breaker.send(:on_failure)
+          end
+        end
+      end
+
+      nil
+    end
+
+    def log_debug(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.debug(message)
+      else
+        $stdout.puts(message)
+      end
+    end
+  end
+end
+
+