brainzlab 0.1.33 → 0.1.35

data/lib/brainzlab/configuration.rb

@@ -45,6 +45,9 @@ module BrainzLab
                   :pulse_sample_tier,
                   :pulse_always_keep_slow_ms,
                   :pulse_excluded_paths,
+                  :pulse_explain_enabled,
+                  :pulse_explain_threshold,
+                  :pulse_explain_timeout,
                   :flux_enabled,
                   :flux_url,
                   :flux_api_key,
@@ -196,262 +199,13 @@ module BrainzLab
     }.freeze
 
     def initialize
-      # SDK enabled flag — set BRAINZLAB_SDK_ENABLED=false to completely disable
-      @enabled = ENV.fetch('BRAINZLAB_SDK_ENABLED', 'true') != 'false'
-
-      # Authentication
-      @secret_key = ENV.fetch('BRAINZLAB_SECRET_KEY', nil)
-
-      # Environment
-      @environment = ENV['BRAINZLAB_ENVIRONMENT'] || detect_environment
-      @service = ENV.fetch('BRAINZLAB_SERVICE', nil)
-      @host = ENV['BRAINZLAB_HOST'] || detect_host
-
-      # App name for auto-provisioning
-      @app_name = ENV.fetch('BRAINZLAB_APP_NAME', nil)
-
-      # Git context
-      @commit = ENV['GIT_COMMIT'] || ENV['COMMIT_SHA'] || detect_git_commit
-      @branch = ENV['GIT_BRANCH'] || ENV['BRANCH_NAME'] || detect_git_branch
-
-      # Debug mode - enables verbose logging
-      @debug = ENV['BRAINZLAB_DEBUG'] == 'true'
-
-      # SDK mode - :production (default) or :development (offline, local storage)
-      @mode = ENV['BRAINZLAB_MODE']&.to_sym || :production
-
-      # Development mode settings
-      @development_db_path = ENV['BRAINZLAB_DEV_DB_PATH'] || 'tmp/brainzlab.sqlite3'
-      @development_log_output = $stdout
-
-      # Disable self-tracking - prevents services from tracking to themselves
-      # e.g., Recall won't log to itself, Reflex won't track errors to itself
-      @disable_self_tracking = ENV.fetch('BRAINZLAB_DISABLE_SELF_TRACKING', 'true') == 'true'
-
-      # Recall settings
-      @recall_enabled = true
-      @recall_url = ENV['RECALL_URL'] || detect_product_url('recall')
-      @recall_min_level = :debug
-      @recall_buffer_size = 50
-      @recall_flush_interval = 5
-      @recall_master_key = ENV.fetch('RECALL_MASTER_KEY', nil)
-      @recall_auto_provision = true
-
-      # Reflex settings
-      @reflex_enabled = true
-      @reflex_url = ENV['REFLEX_URL'] || detect_product_url('reflex')
-      @reflex_api_key = ENV.fetch('REFLEX_API_KEY', nil)
-      @reflex_master_key = ENV.fetch('REFLEX_MASTER_KEY', nil)
-      @reflex_auto_provision = true
-      @reflex_excluded_exceptions = []
-      @reflex_before_send = nil
-      @reflex_sample_rate = nil
-      @reflex_fingerprint = nil # Custom fingerprint callback
-
-      # Pulse settings
-      @pulse_enabled = true
-      @pulse_url = ENV['PULSE_URL'] || detect_product_url('pulse')
-      @pulse_api_key = ENV.fetch('PULSE_API_KEY', nil)
-      @pulse_master_key = ENV.fetch('PULSE_MASTER_KEY', nil)
-      @pulse_auto_provision = true
-      @pulse_buffer_size = 50
-      @pulse_flush_interval = 5
-      # Trace sampling. Explicit rate (0.0–1.0) wins; otherwise derived from the
-      # tier. Defaults to the "internal" tier so the Brainz fleet samples ~10%
-      # (error traces are always kept). Client-facing apps set
-      # BRAINZLAB_PULSE_TIER=client (or PULSE_SAMPLE_RATE) to keep everything.
-      @pulse_sample_rate = (v = ENV['PULSE_SAMPLE_RATE'] || ENV['BRAINZLAB_PULSE_SAMPLE_RATE']).nil? || v.to_s.strip.empty? ? nil : v.to_f
-      @pulse_sample_tier = (ENV['BRAINZLAB_PULSE_TIER'] || 'internal').to_s.strip.downcase
-      # Traces at/above this duration (ms) bypass sampling and are ALWAYS kept,
-      # so slow requests / N+1s are never sampled away (APM's whole purpose).
-      # Set to 0 to disable. Default 1000ms.
-      @pulse_always_keep_slow_ms = (ENV['BRAINZLAB_PULSE_ALWAYS_KEEP_SLOW_MS'] || 1000).to_i
-      @pulse_excluded_paths = %w[/health /ping /up /assets]
-
-      # Flux settings
-      @flux_enabled = true
-      @flux_url = ENV['FLUX_URL'] || 'https://flux.brainzlab.ai'
-      @flux_api_key = ENV.fetch('FLUX_API_KEY', nil)
-      @flux_ingest_key = ENV.fetch('FLUX_INGEST_KEY', nil)
-      @flux_master_key = ENV.fetch('FLUX_MASTER_KEY', nil)
-      @flux_auto_provision = true
-      @flux_buffer_size = 100
-      @flux_flush_interval = 5
-
-      # Signal settings
-      @signal_enabled = true
-      @signal_url = ENV['SIGNAL_URL'] || detect_product_url('signal')
-      @signal_api_key = ENV.fetch('SIGNAL_API_KEY', nil)
-      @signal_ingest_key = ENV.fetch('SIGNAL_INGEST_KEY', nil)
-      @signal_master_key = ENV.fetch('SIGNAL_MASTER_KEY', nil)
-      @signal_auto_provision = true
-
-      # Vault settings
-      @vault_enabled = true
-      @vault_url = ENV['VAULT_URL'] || 'https://vault.brainzlab.ai'
-      @vault_api_key = ENV.fetch('VAULT_API_KEY', nil)
-      @vault_master_key = ENV.fetch('VAULT_MASTER_KEY', nil)
-      @vault_auto_provision = true
-      @vault_cache_enabled = true
-      @vault_cache_ttl = 300 # 5 minutes
-      @vault_auto_load = ENV.fetch('VAULT_AUTO_LOAD', 'false') == 'true' # Auto-load secrets into ENV
-      @vault_load_provider_keys = true # Also load provider keys (OpenAI, etc.)
-
-      # Vision settings (AI browser automation)
-      @vision_enabled = true
-      @vision_url = ENV['VISION_URL'] || 'https://vision.brainzlab.ai'
-      @vision_api_key = ENV.fetch('VISION_API_KEY', nil)
-      @vision_ingest_key = ENV.fetch('VISION_INGEST_KEY', nil)
-      @vision_master_key = ENV.fetch('VISION_MASTER_KEY', nil)
-      @vision_auto_provision = true
-      @vision_default_model = ENV['VISION_DEFAULT_MODEL'] || 'claude-sonnet-4'
-      @vision_default_browser_provider = ENV['VISION_DEFAULT_BROWSER_PROVIDER'] || 'local'
-
-      # Cortex settings (feature flags)
-      @cortex_enabled = true
-      @cortex_url = ENV['CORTEX_URL'] || 'https://cortex.brainzlab.ai'
-      @cortex_api_key = ENV.fetch('CORTEX_API_KEY', nil)
-      @cortex_master_key = ENV.fetch('CORTEX_MASTER_KEY', nil)
-      @cortex_auto_provision = true
-      @cortex_cache_enabled = true
-      @cortex_cache_ttl = 60 # 1 minute
-      @cortex_default_context = {}
-
-      # Beacon settings (uptime monitoring)
-      @beacon_enabled = true
-      @beacon_url = ENV['BEACON_URL'] || 'https://beacon.brainzlab.ai'
-      @beacon_api_key = ENV.fetch('BEACON_API_KEY', nil)
-      @beacon_master_key = ENV.fetch('BEACON_MASTER_KEY', nil)
-      @beacon_auto_provision = true
-
-      # Nerve settings (job monitoring)
-      @nerve_enabled = true
-      @nerve_url = ENV['NERVE_URL'] || 'https://nerve.brainzlab.ai'
-      @nerve_api_key = ENV.fetch('NERVE_API_KEY', nil)
-      @nerve_master_key = ENV.fetch('NERVE_MASTER_KEY', nil)
-      @nerve_auto_provision = true
-
-      # Dendrite settings (AI documentation)
-      @dendrite_enabled = true
-      @dendrite_url = ENV['DENDRITE_URL'] || 'https://dendrite.brainzlab.ai'
-      @dendrite_api_key = ENV.fetch('DENDRITE_API_KEY', nil)
-      @dendrite_master_key = ENV.fetch('DENDRITE_MASTER_KEY', nil)
-      @dendrite_auto_provision = true
-
-      # Sentinel settings (host monitoring)
-      @sentinel_enabled = true
-      @sentinel_url = ENV['SENTINEL_URL'] || 'https://sentinel.brainzlab.ai'
-      @sentinel_api_key = ENV.fetch('SENTINEL_API_KEY', nil)
-      @sentinel_agent_key = ENV.fetch('SENTINEL_AGENT_KEY', nil)
-      @sentinel_master_key = ENV.fetch('SENTINEL_MASTER_KEY', nil)
-      @sentinel_auto_provision = true
-
-      # Synapse settings (AI development orchestration)
-      @synapse_enabled = true
-      @synapse_url = ENV['SYNAPSE_URL'] || 'https://synapse.brainzlab.ai'
-      @synapse_api_key = ENV.fetch('SYNAPSE_API_KEY', nil)
-      @synapse_master_key = ENV.fetch('SYNAPSE_MASTER_KEY', nil)
-      @synapse_auto_provision = true
-
-      # Filtering
-      @scrub_fields = %i[password password_confirmation token api_key secret]
-
-      # Internal logger for debugging SDK issues
-      @logger = nil
-
-      # Debug callbacks
-      # Called when an SDK error occurs (lambda/proc receiving error object and context hash)
-      @on_error = nil
-      # Called before each API request (lambda/proc receiving service, method, path, and payload)
-      @on_send = nil
-
-      # Instrumentation
-      @instrument_http = true # Enable HTTP client instrumentation (Net::HTTP, Faraday, HTTParty)
-      @instrument_active_record = true # AR breadcrumbs for Reflex
-      @instrument_redis = true # Redis command instrumentation
-      @instrument_sidekiq = true  # Sidekiq job instrumentation
-      @instrument_graphql = true  # GraphQL query instrumentation
-      @instrument_mongodb = true  # MongoDB/Mongoid instrumentation
-      @instrument_elasticsearch = true  # Elasticsearch instrumentation
-      @instrument_action_controller = true  # ActionController instrumentation (requests, redirects, filters)
-      @instrument_action_view = true  # ActionView instrumentation (templates, partials, collections)
-      @instrument_action_mailer = true  # ActionMailer instrumentation
-      @instrument_active_job = true  # ActiveJob instrumentation (enqueue, perform, retry, discard)
-      @instrument_active_support_cache = true  # ActiveSupport::Cache instrumentation (read, write, fetch)
-      @instrument_delayed_job = true # Delayed::Job instrumentation
-      @instrument_grape = true # Grape API instrumentation
-      @instrument_solid_queue = true # Solid Queue job instrumentation
-      @instrument_good_job = true # GoodJob instrumentation
-      @instrument_resque = true # Resque instrumentation
-      @instrument_excon = true # Excon HTTP client instrumentation
-      @instrument_typhoeus = true # Typhoeus HTTP client instrumentation
-      @instrument_dalli = true # Dalli/Memcached instrumentation
-      @instrument_aws = true # AWS SDK instrumentation
-      @instrument_stripe = true # Stripe API instrumentation
-      @instrument_active_storage = true # ActiveStorage instrumentation (uploads, downloads, transforms)
-      @instrument_action_cable = true # ActionCable WebSocket instrumentation
-      @instrument_action_dispatch = true # ActionDispatch instrumentation (middleware, redirects, requests)
-      @instrument_rails_deprecation = true # Rails deprecation warnings tracking
-      @instrument_action_mailbox = true # ActionMailbox inbound email processing instrumentation
-      @instrument_railties = true # Railties config initializer loading instrumentation
-      @http_ignore_hosts = %w[localhost 127.0.0.1]
-      @redis_ignore_commands = %w[ping info] # Commands to skip tracking
-
-      # ActiveRecord slow-query / N+1 detection — all tunable so a single chatty
-      # default can't flood Recall. Slow-query duration is APM data (Pulse already
-      # records it), so it defaults to a quiet level (:debug) and a higher threshold.
-      @slow_query_threshold       = (ENV['BRAINZLAB_SLOW_QUERY_THRESHOLD'] || 500).to_i      # ms (was hardcoded 100)
-      @very_slow_query_threshold  = (ENV['BRAINZLAB_VERY_SLOW_QUERY_THRESHOLD'] || 2000).to_i # ms (was hardcoded 1000)
-      @slow_query_log_level       = (ENV['BRAINZLAB_SLOW_QUERY_LOG_LEVEL'] || 'debug').to_sym  # was :warn → floods
-      @very_slow_query_log_level  = (ENV['BRAINZLAB_VERY_SLOW_QUERY_LOG_LEVEL'] || 'warn').to_sym
-      @n_plus_one_threshold       = (ENV['BRAINZLAB_N_PLUS_ONE_THRESHOLD'] || 10).to_i        # was hardcoded 5
-      @n_plus_one_log_level       = (ENV['BRAINZLAB_N_PLUS_ONE_LOG_LEVEL'] || 'debug').to_sym  # was :warning
-
-      # Per-instrumentation slow / very-slow thresholds (ms) — all env-tunable so a
-      # single low default can't flood Recall or wrongly escalate normal latency to
-      # :error. Defaults preserve prior behaviour EXCEPT cache, which is raised off
-      # DB-backed Solid Cache's normal write latency (~50ms paid a DB round-trip and
-      # tripped the old VERY_SLOW=50 → thousands of false :error logs/hour).
-      @slow_request_threshold         = (ENV['BRAINZLAB_SLOW_REQUEST_THRESHOLD'] || 500).to_i
-      @very_slow_request_threshold    = (ENV['BRAINZLAB_VERY_SLOW_REQUEST_THRESHOLD'] || 2000).to_i
-      @slow_cache_threshold           = (ENV['BRAINZLAB_SLOW_CACHE_THRESHOLD'] || 100).to_i        # was 10
-      @very_slow_cache_threshold      = (ENV['BRAINZLAB_VERY_SLOW_CACHE_THRESHOLD'] || 500).to_i   # was 50 → flooded :error
-      @slow_render_threshold          = (ENV['BRAINZLAB_SLOW_RENDER_THRESHOLD'] || 50).to_i
-      @very_slow_render_threshold     = (ENV['BRAINZLAB_VERY_SLOW_RENDER_THRESHOLD'] || 200).to_i
-      @slow_storage_threshold         = (ENV['BRAINZLAB_SLOW_STORAGE_THRESHOLD'] || 500).to_i
-      @very_slow_storage_threshold    = (ENV['BRAINZLAB_VERY_SLOW_STORAGE_THRESHOLD'] || 2000).to_i
-      @slow_cable_threshold           = (ENV['BRAINZLAB_SLOW_CABLE_THRESHOLD'] || 100).to_i
-      @very_slow_cable_threshold      = (ENV['BRAINZLAB_VERY_SLOW_CABLE_THRESHOLD'] || 500).to_i
-      @slow_initializer_threshold     = (ENV['BRAINZLAB_SLOW_INITIALIZER_THRESHOLD'] || 100).to_i
-      @very_slow_initializer_threshold = (ENV['BRAINZLAB_VERY_SLOW_INITIALIZER_THRESHOLD'] || 500).to_i
-      @slow_middleware_threshold      = (ENV['BRAINZLAB_SLOW_MIDDLEWARE_THRESHOLD'] || 50).to_i
-      @very_slow_middleware_threshold = (ENV['BRAINZLAB_VERY_SLOW_MIDDLEWARE_THRESHOLD'] || 200).to_i
-      @slow_mailbox_threshold         = (ENV['BRAINZLAB_SLOW_MAILBOX_THRESHOLD'] || 1000).to_i
-      @very_slow_mailbox_threshold    = (ENV['BRAINZLAB_VERY_SLOW_MAILBOX_THRESHOLD'] || 5000).to_i
-      @slow_job_threshold             = (ENV['BRAINZLAB_SLOW_JOB_THRESHOLD'] || 5000).to_i
-      @very_slow_job_threshold        = (ENV['BRAINZLAB_VERY_SLOW_JOB_THRESHOLD'] || 30_000).to_i
-
-      # Log formatter settings
-      @log_formatter_enabled = true
-      @log_formatter_colors = nil # auto-detect TTY
-      @log_formatter_hide_assets = false
-      @log_formatter_compact_assets = true
-      @log_formatter_show_params = true
-
-      # DevTools settings (development error page and debug panel)
-      @devtools_enabled = true
-      @devtools_error_page_enabled = true
-      @devtools_debug_panel_enabled = true
-      @devtools_allowed_environments = %w[development test]
-      @devtools_allowed_ips = ['127.0.0.1', '::1', '172.16.0.0/12', '192.168.0.0/16', '10.0.0.0/8']
-      @devtools_asset_path = '/__brainzlab__'
-      @devtools_panel_position = 'bottom-right'
-      @devtools_expand_by_default = false
-
-      # Rails instrumentation delegation
-      # When true, brainzlab-rails gem handles Rails-specific instrumentation
-      # SDK will only install non-Rails instrumentation (HTTP clients, Redis, etc.)
-      @rails_instrumentation_handled_externally = false
+      init_core_defaults
+      init_observability_defaults
+      init_platform_defaults
+      init_runtime_defaults
+      init_instrumentation_defaults
+      init_threshold_defaults
+      init_presentation_defaults
     end
 
     def recall_min_level=(level)
@@ -498,6 +252,63 @@ module BrainzLab
       @enabled && !@secret_key.nil? && !@secret_key.empty?
     end
 
+    # Settings validated eagerly by #validate!, grouped by the shape they must
+    # have. Kept as data so adding a setting is a one-line change here rather
+    # than another branch in the validation logic.
+    SAMPLE_RATE_SETTINGS = %i[pulse_sample_rate reflex_sample_rate].freeze
+
+    POSITIVE_INTEGER_SETTINGS = %i[
+      recall_buffer_size recall_flush_interval
+      pulse_buffer_size pulse_flush_interval
+      flux_buffer_size flux_flush_interval
+      pulse_explain_timeout
+    ].freeze
+
+    NON_NEGATIVE_NUMBER_SETTINGS = %i[
+      pulse_always_keep_slow_ms
+      slow_query_threshold very_slow_query_threshold
+      slow_request_threshold very_slow_request_threshold
+      n_plus_one_threshold pulse_explain_threshold
+    ].freeze
+
+    # Validate the configuration and raise on anything that would misbehave
+    # silently at runtime. Called by BrainzLab.configure once the user's block
+    # has been applied, so a typo surfaces at boot rather than as missing
+    # telemetry days later.
+    #
+    # @return [Configuration] self, when every setting is valid
+    # @raise [ConfigurationError] listing every invalid setting at once
+    def validate!
+      problems = []
+
+      SAMPLE_RATE_SETTINGS.each do |setting|
+        value = public_send(setting)
+        next if value.nil? # nil means "fall back to the tier default"
+
+        problems << "#{setting} must be a number between 0 and 1 (got #{value.inspect})" unless value.is_a?(Numeric) && value.between?(0, 1)
+      end
+
+      POSITIVE_INTEGER_SETTINGS.each do |setting|
+        value = public_send(setting)
+        problems << "#{setting} must be a positive number (got #{value.inspect})" unless positive_number?(value)
+      end
+
+      NON_NEGATIVE_NUMBER_SETTINGS.each do |setting|
+        value = public_send(setting)
+        problems << "#{setting} must be a non-negative number (got #{value.inspect})" unless value.is_a?(Numeric) && !value.negative?
+      end
+
+      return self if problems.empty?
+
+      raise ConfigurationError.new(
+        "Invalid BrainzLab configuration: #{problems.join('; ')}",
+        hint: 'Fix these values in your BrainzLab.configure block or the matching environment variables. ' \
+              'Sample rates are fractions (0.5 = 50%), not percentages.',
+        code: 'invalid_configuration',
+        context: { problems: problems }
+      )
+    end
+
     def enabled?
       @enabled == true
     end
@@ -526,7 +337,7 @@ module BrainzLab
     PULSE_TIER_SAMPLE_RATES = {
       'internal' => 0.1,
       'standard' => 0.5,
-      'client'   => 1.0,
+      'client' => 1.0,
       'critical' => 1.0
     }.freeze
 
@@ -642,7 +453,11 @@ module BrainzLab
           @synapse_url
         ].compact
 
-        urls.filter_map { |url| URI.parse(url).host rescue nil }.uniq
+        urls.filter_map do |url|
+          URI.parse(url).host
+        rescue StandardError
+          nil
+        end.uniq
       end
     end
 
@@ -714,6 +529,296 @@ module BrainzLab
 
     private
 
+    # Core identity: enablement, auth, environment, git context, SDK mode.
+    def init_core_defaults
+      # SDK enabled flag — set BRAINZLAB_SDK_ENABLED=false to completely disable
+      @enabled = ENV.fetch('BRAINZLAB_SDK_ENABLED', 'true') != 'false'
+
+      # Authentication
+      @secret_key = ENV.fetch('BRAINZLAB_SECRET_KEY', nil)
+
+      # Environment
+      @environment = ENV['BRAINZLAB_ENVIRONMENT'] || detect_environment
+      @service = ENV.fetch('BRAINZLAB_SERVICE', nil)
+      @host = ENV['BRAINZLAB_HOST'] || detect_host
+
+      # App name for auto-provisioning
+      @app_name = ENV.fetch('BRAINZLAB_APP_NAME', nil)
+
+      # Git context
+      @commit = ENV['GIT_COMMIT'] || ENV['COMMIT_SHA'] || detect_git_commit
+      @branch = ENV['GIT_BRANCH'] || ENV['BRANCH_NAME'] || detect_git_branch
+
+      # Debug mode - enables verbose logging
+      @debug = ENV['BRAINZLAB_DEBUG'] == 'true'
+
+      # SDK mode - :production (default) or :development (offline, local storage)
+      @mode = ENV['BRAINZLAB_MODE']&.to_sym || :production
+
+      # Development mode settings
+      @development_db_path = ENV['BRAINZLAB_DEV_DB_PATH'] || 'tmp/brainzlab.sqlite3'
+      @development_log_output = $stdout
+
+      # Disable self-tracking - prevents services from tracking to themselves
+      # e.g., Recall won't log to itself, Reflex won't track errors to itself
+      @disable_self_tracking = ENV.fetch('BRAINZLAB_DISABLE_SELF_TRACKING', 'true') == 'true'
+    end
+
+    # The five observability products: Recall, Reflex, Pulse, Flux, Signal.
+    def init_observability_defaults
+      # Recall settings
+      @recall_enabled = true
+      @recall_url = ENV['RECALL_URL'] || detect_product_url('recall')
+      @recall_min_level = :debug
+      @recall_buffer_size = 50
+      @recall_flush_interval = 5
+      @recall_master_key = ENV.fetch('RECALL_MASTER_KEY', nil)
+      @recall_auto_provision = true
+
+      # Reflex settings
+      @reflex_enabled = true
+      @reflex_url = ENV['REFLEX_URL'] || detect_product_url('reflex')
+      @reflex_api_key = ENV.fetch('REFLEX_API_KEY', nil)
+      @reflex_master_key = ENV.fetch('REFLEX_MASTER_KEY', nil)
+      @reflex_auto_provision = true
+      @reflex_excluded_exceptions = []
+      @reflex_before_send = nil
+      @reflex_sample_rate = nil
+      @reflex_fingerprint = nil # Custom fingerprint callback
+
+      # Pulse settings
+      @pulse_enabled = true
+      @pulse_url = ENV['PULSE_URL'] || detect_product_url('pulse')
+      @pulse_api_key = ENV.fetch('PULSE_API_KEY', nil)
+      @pulse_master_key = ENV.fetch('PULSE_MASTER_KEY', nil)
+      @pulse_auto_provision = true
+      @pulse_buffer_size = 50
+      @pulse_flush_interval = 5
+      # Trace sampling. Explicit rate (0.0–1.0) wins; otherwise derived from the
+      # tier. Defaults to the "internal" tier so the Brainz fleet samples ~10%
+      # (error traces are always kept). Client-facing apps set
+      # BRAINZLAB_PULSE_TIER=client (or PULSE_SAMPLE_RATE) to keep everything.
+      @pulse_sample_rate = (v = ENV['PULSE_SAMPLE_RATE'] || ENV.fetch('BRAINZLAB_PULSE_SAMPLE_RATE', nil)).nil? || v.to_s.strip.empty? ? nil : v.to_f
+      @pulse_sample_tier = (ENV['BRAINZLAB_PULSE_TIER'] || 'internal').to_s.strip.downcase
+      # Traces at/above this duration (ms) bypass sampling and are ALWAYS kept,
+      # so slow requests / N+1s are never sampled away (APM's whole purpose).
+      # Set to 0 to disable. Default 1000ms.
+      @pulse_always_keep_slow_ms = (ENV['BRAINZLAB_PULSE_ALWAYS_KEEP_SLOW_MS'] || 1000).to_i
+      @pulse_excluded_paths = %w[/health /ping /up /assets]
+
+      # Flux settings
+      @flux_enabled = true
+      @flux_url = ENV['FLUX_URL'] || 'https://flux.brainzlab.ai'
+      @flux_api_key = ENV.fetch('FLUX_API_KEY', nil)
+      @flux_ingest_key = ENV.fetch('FLUX_INGEST_KEY', nil)
+      @flux_master_key = ENV.fetch('FLUX_MASTER_KEY', nil)
+      @flux_auto_provision = true
+      @flux_buffer_size = 100
+      @flux_flush_interval = 5
+
+      # Signal settings
+      @signal_enabled = true
+      @signal_url = ENV['SIGNAL_URL'] || detect_product_url('signal')
+      @signal_api_key = ENV.fetch('SIGNAL_API_KEY', nil)
+      @signal_ingest_key = ENV.fetch('SIGNAL_INGEST_KEY', nil)
+      @signal_master_key = ENV.fetch('SIGNAL_MASTER_KEY', nil)
+      @signal_auto_provision = true
+    end
+
+    # The platform services: Vault, Vision, Cortex, Beacon, Nerve, Dendrite, Sentinel, Synapse.
+    def init_platform_defaults
+      # Vault settings
+      @vault_enabled = true
+      @vault_url = ENV['VAULT_URL'] || 'https://vault.brainzlab.ai'
+      @vault_api_key = ENV.fetch('VAULT_API_KEY', nil)
+      @vault_master_key = ENV.fetch('VAULT_MASTER_KEY', nil)
+      @vault_auto_provision = true
+      @vault_cache_enabled = true
+      @vault_cache_ttl = 300 # 5 minutes
+      @vault_auto_load = ENV.fetch('VAULT_AUTO_LOAD', 'false') == 'true' # Auto-load secrets into ENV
+      @vault_load_provider_keys = true # Also load provider keys (OpenAI, etc.)
+
+      # Vision settings (AI browser automation)
+      @vision_enabled = true
+      @vision_url = ENV['VISION_URL'] || 'https://vision.brainzlab.ai'
+      @vision_api_key = ENV.fetch('VISION_API_KEY', nil)
+      @vision_ingest_key = ENV.fetch('VISION_INGEST_KEY', nil)
+      @vision_master_key = ENV.fetch('VISION_MASTER_KEY', nil)
+      @vision_auto_provision = true
+      @vision_default_model = ENV['VISION_DEFAULT_MODEL'] || 'claude-sonnet-4'
+      @vision_default_browser_provider = ENV['VISION_DEFAULT_BROWSER_PROVIDER'] || 'local'
+
+      # Cortex settings (feature flags)
+      @cortex_enabled = true
+      @cortex_url = ENV['CORTEX_URL'] || 'https://cortex.brainzlab.ai'
+      @cortex_api_key = ENV.fetch('CORTEX_API_KEY', nil)
+      @cortex_master_key = ENV.fetch('CORTEX_MASTER_KEY', nil)
+      @cortex_auto_provision = true
+      @cortex_cache_enabled = true
+      @cortex_cache_ttl = 60 # 1 minute
+      @cortex_default_context = {}
+
+      # Beacon settings (uptime monitoring)
+      @beacon_enabled = true
+      @beacon_url = ENV['BEACON_URL'] || 'https://beacon.brainzlab.ai'
+      @beacon_api_key = ENV.fetch('BEACON_API_KEY', nil)
+      @beacon_master_key = ENV.fetch('BEACON_MASTER_KEY', nil)
+      @beacon_auto_provision = true
+
+      # Nerve settings (job monitoring)
+      @nerve_enabled = true
+      @nerve_url = ENV['NERVE_URL'] || 'https://nerve.brainzlab.ai'
+      @nerve_api_key = ENV.fetch('NERVE_API_KEY', nil)
+      @nerve_master_key = ENV.fetch('NERVE_MASTER_KEY', nil)
+      @nerve_auto_provision = true
+
+      # Dendrite settings (AI documentation)
+      @dendrite_enabled = true
+      @dendrite_url = ENV['DENDRITE_URL'] || 'https://dendrite.brainzlab.ai'
+      @dendrite_api_key = ENV.fetch('DENDRITE_API_KEY', nil)
+      @dendrite_master_key = ENV.fetch('DENDRITE_MASTER_KEY', nil)
+      @dendrite_auto_provision = true
+
+      # Sentinel settings (host monitoring)
+      @sentinel_enabled = true
+      @sentinel_url = ENV['SENTINEL_URL'] || 'https://sentinel.brainzlab.ai'
+      @sentinel_api_key = ENV.fetch('SENTINEL_API_KEY', nil)
+      @sentinel_agent_key = ENV.fetch('SENTINEL_AGENT_KEY', nil)
+      @sentinel_master_key = ENV.fetch('SENTINEL_MASTER_KEY', nil)
+      @sentinel_auto_provision = true
+
+      # Synapse settings (AI development orchestration)
+      @synapse_enabled = true
+      @synapse_url = ENV['SYNAPSE_URL'] || 'https://synapse.brainzlab.ai'
+      @synapse_api_key = ENV.fetch('SYNAPSE_API_KEY', nil)
+      @synapse_master_key = ENV.fetch('SYNAPSE_MASTER_KEY', nil)
+      @synapse_auto_provision = true
+    end
+
+    # Scrubbing, internal logger and debug callbacks.
+    def init_runtime_defaults
+      # Filtering
+      @scrub_fields = %i[password password_confirmation token api_key secret]
+
+      # Internal logger for debugging SDK issues
+      @logger = nil
+
+      # Debug callbacks
+      # Called when an SDK error occurs (lambda/proc receiving error object and context hash)
+      @on_error = nil
+      # Called before each API request (lambda/proc receiving service, method, path, and payload)
+      @on_send = nil
+    end
+
+    # Which integrations auto-instrument, and what they ignore.
+    def init_instrumentation_defaults
+      # Instrumentation
+      @instrument_http = true # Enable HTTP client instrumentation (Net::HTTP, Faraday, HTTParty)
+      @instrument_active_record = true # AR breadcrumbs for Reflex
+      @instrument_redis = true # Redis command instrumentation
+      @instrument_sidekiq = true  # Sidekiq job instrumentation
+      @instrument_graphql = true  # GraphQL query instrumentation
+      @instrument_mongodb = true  # MongoDB/Mongoid instrumentation
+      @instrument_elasticsearch = true # Elasticsearch instrumentation
+      @instrument_action_controller = true # ActionController instrumentation (requests, redirects, filters)
+      @instrument_action_view = true # ActionView instrumentation (templates, partials, collections)
+      @instrument_action_mailer = true # ActionMailer instrumentation
+      @instrument_active_job = true # ActiveJob instrumentation (enqueue, perform, retry, discard)
+      @instrument_active_support_cache = true # ActiveSupport::Cache instrumentation (read, write, fetch)
+      @instrument_delayed_job = true # Delayed::Job instrumentation
+      @instrument_grape = true # Grape API instrumentation
+      @instrument_solid_queue = true # Solid Queue job instrumentation
+      @instrument_good_job = true # GoodJob instrumentation
+      @instrument_resque = true # Resque instrumentation
+      @instrument_excon = true # Excon HTTP client instrumentation
+      @instrument_typhoeus = true # Typhoeus HTTP client instrumentation
+      @instrument_dalli = true # Dalli/Memcached instrumentation
+      @instrument_aws = true # AWS SDK instrumentation
+      @instrument_stripe = true # Stripe API instrumentation
+      @instrument_active_storage = true # ActiveStorage instrumentation (uploads, downloads, transforms)
+      @instrument_action_cable = true # ActionCable WebSocket instrumentation
+      @instrument_action_dispatch = true # ActionDispatch instrumentation (middleware, redirects, requests)
+      @instrument_rails_deprecation = true # Rails deprecation warnings tracking
+      @instrument_action_mailbox = true # ActionMailbox inbound email processing instrumentation
+      @instrument_railties = true # Railties config initializer loading instrumentation
+      @http_ignore_hosts = %w[localhost 127.0.0.1]
+      @redis_ignore_commands = %w[ping info] # Commands to skip tracking
+    end
+
+    # Slow / very-slow thresholds and N+1 detection, all env-tunable.
+    def init_threshold_defaults
+      # ActiveRecord slow-query / N+1 detection — all tunable so a single chatty
+      # default can't flood Recall. Slow-query duration is APM data (Pulse already
+      # records it), so it defaults to a quiet level (:debug) and a higher threshold.
+      @slow_query_threshold = (ENV['BRAINZLAB_SLOW_QUERY_THRESHOLD'] || 500).to_i # ms (was hardcoded 100)
+
+      # Query plan capture. Off by default: it issues an extra (read-only)
+      # EXPLAIN against the app's own database, so an app opts in deliberately.
+      # Threshold defaults to the slow query threshold — a fast query has no
+      # plan worth looking at.
+      @pulse_explain_enabled = ENV['BRAINZLAB_PULSE_EXPLAIN_ENABLED'] == 'true'
+      @pulse_explain_threshold = (ENV['BRAINZLAB_PULSE_EXPLAIN_THRESHOLD'] || @slow_query_threshold).to_i
+      @pulse_explain_timeout = (ENV['BRAINZLAB_PULSE_EXPLAIN_TIMEOUT'] || 2).to_i
+      @very_slow_query_threshold  = (ENV['BRAINZLAB_VERY_SLOW_QUERY_THRESHOLD'] || 2000).to_i # ms (was hardcoded 1000)
+      @slow_query_log_level       = (ENV['BRAINZLAB_SLOW_QUERY_LOG_LEVEL'] || 'debug').to_sym # was :warn → floods
+      @very_slow_query_log_level  = (ENV['BRAINZLAB_VERY_SLOW_QUERY_LOG_LEVEL'] || 'warn').to_sym
+      @n_plus_one_threshold       = (ENV['BRAINZLAB_N_PLUS_ONE_THRESHOLD'] || 10).to_i # was hardcoded 5
+      @n_plus_one_log_level       = (ENV['BRAINZLAB_N_PLUS_ONE_LOG_LEVEL'] || 'debug').to_sym # was :warning
+
+      # Per-instrumentation slow / very-slow thresholds (ms) — all env-tunable so a
+      # single low default can't flood Recall or wrongly escalate normal latency to
+      # :error. Defaults preserve prior behaviour EXCEPT cache, which is raised off
+      # DB-backed Solid Cache's normal write latency (~50ms paid a DB round-trip and
+      # tripped the old VERY_SLOW=50 → thousands of false :error logs/hour).
+      @slow_request_threshold         = (ENV['BRAINZLAB_SLOW_REQUEST_THRESHOLD'] || 500).to_i
+      @very_slow_request_threshold    = (ENV['BRAINZLAB_VERY_SLOW_REQUEST_THRESHOLD'] || 2000).to_i
+      @slow_cache_threshold           = (ENV['BRAINZLAB_SLOW_CACHE_THRESHOLD'] || 100).to_i        # was 10
+      @very_slow_cache_threshold      = (ENV['BRAINZLAB_VERY_SLOW_CACHE_THRESHOLD'] || 500).to_i   # was 50 → flooded :error
+      @slow_render_threshold          = (ENV['BRAINZLAB_SLOW_RENDER_THRESHOLD'] || 50).to_i
+      @very_slow_render_threshold     = (ENV['BRAINZLAB_VERY_SLOW_RENDER_THRESHOLD'] || 200).to_i
+      @slow_storage_threshold         = (ENV['BRAINZLAB_SLOW_STORAGE_THRESHOLD'] || 500).to_i
+      @very_slow_storage_threshold    = (ENV['BRAINZLAB_VERY_SLOW_STORAGE_THRESHOLD'] || 2000).to_i
+      @slow_cable_threshold           = (ENV['BRAINZLAB_SLOW_CABLE_THRESHOLD'] || 100).to_i
+      @very_slow_cable_threshold      = (ENV['BRAINZLAB_VERY_SLOW_CABLE_THRESHOLD'] || 500).to_i
+      @slow_initializer_threshold     = (ENV['BRAINZLAB_SLOW_INITIALIZER_THRESHOLD'] || 100).to_i
+      @very_slow_initializer_threshold = (ENV['BRAINZLAB_VERY_SLOW_INITIALIZER_THRESHOLD'] || 500).to_i
+      @slow_middleware_threshold      = (ENV['BRAINZLAB_SLOW_MIDDLEWARE_THRESHOLD'] || 50).to_i
+      @very_slow_middleware_threshold = (ENV['BRAINZLAB_VERY_SLOW_MIDDLEWARE_THRESHOLD'] || 200).to_i
+      @slow_mailbox_threshold         = (ENV['BRAINZLAB_SLOW_MAILBOX_THRESHOLD'] || 1000).to_i
+      @very_slow_mailbox_threshold    = (ENV['BRAINZLAB_VERY_SLOW_MAILBOX_THRESHOLD'] || 5000).to_i
+      @slow_job_threshold             = (ENV['BRAINZLAB_SLOW_JOB_THRESHOLD'] || 5000).to_i
+      @very_slow_job_threshold        = (ENV['BRAINZLAB_VERY_SLOW_JOB_THRESHOLD'] || 30_000).to_i
+    end
+
+    # Log formatter, DevTools and Rails delegation.
+    def init_presentation_defaults
+      # Log formatter settings
+      @log_formatter_enabled = true
+      @log_formatter_colors = nil # auto-detect TTY
+      @log_formatter_hide_assets = false
+      @log_formatter_compact_assets = true
+      @log_formatter_show_params = true
+
+      # DevTools settings (development error page and debug panel)
+      @devtools_enabled = true
+      @devtools_error_page_enabled = true
+      @devtools_debug_panel_enabled = true
+      @devtools_allowed_environments = %w[development test]
+      @devtools_allowed_ips = ['127.0.0.1', '::1', '172.16.0.0/12', '192.168.0.0/16', '10.0.0.0/8']
+      @devtools_asset_path = '/__brainzlab__'
+      @devtools_panel_position = 'bottom-right'
+      @devtools_expand_by_default = false
+
+      # Rails instrumentation delegation
+      # When true, brainzlab-rails gem handles Rails-specific instrumentation
+      # SDK will only install non-Rails instrumentation (HTTP clients, Redis, etc.)
+      @rails_instrumentation_handled_externally = false
+    end
+
+    def positive_number?(value)
+      value.is_a?(Numeric) && value.positive?
+    end
+
     def detect_environment
       return ::Rails.env.to_s if defined?(::Rails) && ::Rails.respond_to?(:env)
       return ENV['RACK_ENV'] if ENV['RACK_ENV']