brainzlab 0.1.11 → 0.1.20

data/lib/brainzlab/flux/client.rb

@@ -48,11 +48,11 @@ module BrainzLab
 
         response = http.request(request)
 
-        BrainzLab.debug("[Flux] Request failed: #{response.code} - #{response.body}") unless response.is_a?(Net::HTTPSuccess)
+        BrainzLab.debug_log("[Flux] Request failed: #{response.code} - #{response.body}") unless response.is_a?(Net::HTTPSuccess)
 
         response
       rescue StandardError => e
-        BrainzLab.debug("[Flux] Request error: #{e.message}")
+        BrainzLab.debug_log("[Flux] Request error: #{e.message}")
         nil
       end
 

data/lib/brainzlab/instrumentation/active_support_cache.rb

@@ -43,8 +43,10 @@ module BrainzLab
         # ============================================
         def install_cache_read_subscriber!
           ActiveSupport::Notifications.subscribe('cache_read.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_read(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_read(event)
+            end
           end
         end
 
@@ -76,8 +78,10 @@ module BrainzLab
         # ============================================
         def install_cache_read_multi_subscriber!
           ActiveSupport::Notifications.subscribe('cache_read_multi.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_read_multi(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_read_multi(event)
+            end
           end
         end
 
@@ -122,8 +126,10 @@ module BrainzLab
         # ============================================
         def install_cache_write_subscriber!
           ActiveSupport::Notifications.subscribe('cache_write.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_write(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_write(event)
+            end
           end
         end
 
@@ -150,8 +156,10 @@ module BrainzLab
         # ============================================
         def install_cache_write_multi_subscriber!
           ActiveSupport::Notifications.subscribe('cache_write_multi.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_write_multi(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_write_multi(event)
+            end
           end
         end
 
@@ -186,8 +194,10 @@ module BrainzLab
         # ============================================
         def install_cache_delete_subscriber!
           ActiveSupport::Notifications.subscribe('cache_delete.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_delete(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_delete(event)
+            end
           end
         end
 
@@ -211,8 +221,10 @@ module BrainzLab
         # ============================================
         def install_cache_exist_subscriber!
           ActiveSupport::Notifications.subscribe('cache_exist?.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_exist(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_exist(event)
+            end
           end
         end
 
@@ -236,8 +248,10 @@ module BrainzLab
         # ============================================
         def install_cache_fetch_hit_subscriber!
           ActiveSupport::Notifications.subscribe('cache_fetch_hit.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_fetch_hit(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_fetch_hit(event)
+            end
           end
         end
 
@@ -264,8 +278,10 @@ module BrainzLab
         # ============================================
         def install_cache_generate_subscriber!
           ActiveSupport::Notifications.subscribe('cache_generate.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_generate(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_generate(event)
+            end
           end
         end
 
@@ -312,8 +328,10 @@ module BrainzLab
         # ============================================
         def install_cache_increment_subscriber!
           ActiveSupport::Notifications.subscribe('cache_increment.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_increment(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_increment(event)
+            end
           end
         end
 
@@ -349,8 +367,10 @@ module BrainzLab
         # ============================================
         def install_cache_decrement_subscriber!
           ActiveSupport::Notifications.subscribe('cache_decrement.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_decrement(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_decrement(event)
+            end
           end
         end
 
@@ -386,8 +406,10 @@ module BrainzLab
         # ============================================
         def install_cache_delete_multi_subscriber!
           ActiveSupport::Notifications.subscribe('cache_delete_multi.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_delete_multi(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_delete_multi(event)
+            end
           end
         end
 
@@ -422,8 +444,10 @@ module BrainzLab
         # ============================================
         def install_cache_delete_matched_subscriber!
           ActiveSupport::Notifications.subscribe('cache_delete_matched.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_delete_matched(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_delete_matched(event)
+            end
           end
         end
 
@@ -466,8 +490,10 @@ module BrainzLab
         # ============================================
         def install_cache_cleanup_subscriber!
           ActiveSupport::Notifications.subscribe('cache_cleanup.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_cleanup(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_cleanup(event)
+            end
           end
         end
 
@@ -502,8 +528,10 @@ module BrainzLab
         # ============================================
         def install_cache_prune_subscriber!
           ActiveSupport::Notifications.subscribe('cache_prune.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_cache_prune(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_cache_prune(event)
+            end
           end
         end
 
@@ -552,8 +580,10 @@ module BrainzLab
         # ============================================
         def install_message_serializer_fallback_subscriber!
           ActiveSupport::Notifications.subscribe('message_serializer_fallback.active_support') do |*args|
-            event = ActiveSupport::Notifications::Event.new(*args)
-            handle_message_serializer_fallback(event)
+            BrainzLab.with_instrumentation_guard do
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_message_serializer_fallback(event)
+            end
           end
         end
 

data/lib/brainzlab/instrumentation/net_http.rb

@@ -63,6 +63,9 @@ module BrainzLab
 
         def should_track?
           return false unless BrainzLab.configuration.instrument_http
+          # Skip tracking SDK's own HTTP calls to its service endpoints
+          # to prevent recursive cascading (SDK HTTP → track → Recall.debug → buffer → flush → SDK HTTP → ...)
+          return false if BrainzLab.configuration.sdk_service_hosts.include?(address)
 
           ignore_hosts = BrainzLab.configuration.http_ignore_hosts || []
           !ignore_hosts.include?(address)
@@ -82,22 +85,24 @@ module BrainzLab
           duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
           level = error || (status && status >= 400) ? :error : :info
 
-          # Add breadcrumb for Reflex
-          if BrainzLab.configuration.reflex_enabled
-            BrainzLab::Reflex.add_breadcrumb(
-              "#{method} #{url}",
-              category: 'http',
-              level: level,
-              data: { method: method, url: url, status_code: status, duration_ms: duration_ms, error: error }.compact
-            )
-          end
-
-          # Log to Recall at debug level (avoid noise)
-          if BrainzLab.configuration.recall_enabled
-            BrainzLab::Recall.debug(
-              "HTTP #{method} #{url} -> #{status || 'ERROR'}",
-              method: method, url: url, status_code: status, duration_ms: duration_ms, error: error
-            )
+          BrainzLab.with_instrumentation_guard do
+            # Add breadcrumb for Reflex (in-memory, safe)
+            if BrainzLab.configuration.reflex_enabled
+              BrainzLab::Reflex.add_breadcrumb(
+                "#{method} #{url}",
+                category: 'http',
+                level: level,
+                data: { method: method, url: url, status_code: status, duration_ms: duration_ms, error: error }.compact
+              )
+            end
+
+            # Log to Recall at debug level (skipped if already instrumenting)
+            if BrainzLab.configuration.recall_enabled
+              BrainzLab::Recall.debug(
+                "HTTP #{method} #{url} -> #{status || 'ERROR'}",
+                method: method, url: url, status_code: status, duration_ms: duration_ms, error: error
+              )
+            end
           end
         rescue StandardError => e
           # Don't let instrumentation errors crash the app

data/lib/brainzlab/instrumentation.rb

@@ -6,6 +6,12 @@ module BrainzLab
       def install!
         config = BrainzLab.configuration
 
+        # Skip all instrumentation if SDK is disabled
+        unless config.enabled?
+          BrainzLab.debug_log('[Instrumentation] SDK disabled via BRAINZLAB_SDK_ENABLED=false, skipping all instrumentation')
+          return
+        end
+
         # Skip Rails-specific instrumentation if brainzlab-rails gem is handling it
         # This prevents double-tracking of events
         if config.rails_instrumentation_handled_externally

data/lib/brainzlab/nerve/client.rb

@@ -208,7 +208,27 @@ module BrainzLab
       end
 
       def log_error(operation, error)
-        BrainzLab.debug_log("[Nerve::Client] #{operation} failed: #{error.message}")
+        structured_error = ErrorHandler.wrap(error, service: 'Nerve', operation: operation)
+        BrainzLab.debug_log("[Nerve::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Nerve', operation: operation })
+        end
+      end
+
+      def handle_response_error(response, operation)
+        return if response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPCreated) || response.is_a?(Net::HTTPNoContent)
+
+        structured_error = ErrorHandler.from_response(response, service: 'Nerve', operation: operation)
+        BrainzLab.debug_log("[Nerve::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Nerve', operation: operation })
+        end
+
+        structured_error
       end
     end
   end

data/lib/brainzlab/pulse/client.rb

@@ -84,20 +84,29 @@ module BrainzLab
 
       def post(path, body)
         uri = URI.join(@config.pulse_url, path)
+
+        # Call on_send callback if configured
+        invoke_on_send(:pulse, :post, path, body)
+
+        # Log debug output for request
+        log_debug_request(path, body)
+
         request = Net::HTTP::Post.new(uri)
         request['Content-Type'] = 'application/json'
         request['Authorization'] = "Bearer #{@config.pulse_auth_key}"
         request['User-Agent'] = "brainzlab-sdk-ruby/#{BrainzLab::VERSION}"
         request.body = JSON.generate(body)
 
-        execute_with_retry(uri, request)
+        execute_with_retry(uri, request, path)
       rescue StandardError => e
-        log_error("Failed to send to Pulse: #{e.message}")
+        handle_error(e, context: { path: path, body_size: body.to_s.length })
         nil
       end
 
-      def execute_with_retry(uri, request)
+      def execute_with_retry(uri, request, path)
         retries = 0
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         begin
           http = Net::HTTP.new(uri.host, uri.port)
           http.use_ssl = uri.scheme == 'https'
@@ -105,6 +114,10 @@ module BrainzLab
           http.read_timeout = 10
 
           response = http.request(request)
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+
+          # Log debug output for response
+          log_debug_response(response.code.to_i, duration_ms)
 
           case response.code.to_i
           when 200..299
@@ -116,7 +129,10 @@ module BrainzLab
           when 429, 500..599
             raise RetryableError, "Server error: #{response.code}"
           else
-            log_error("Pulse API error: #{response.code} - #{response.body}")
+            handle_error(
+              StandardError.new("Pulse API error: #{response.code}"),
+              context: { path: path, status: response.code, body: response.body }
+            )
             nil
           end
         rescue RetryableError, Net::OpenTimeout, Net::ReadTimeout => e
@@ -125,12 +141,57 @@ module BrainzLab
             sleep(RETRY_DELAY * retries)
             retry
           end
-          log_error("Failed after #{MAX_RETRIES} retries: #{e.message}")
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+          log_debug_response(0, duration_ms, error: e.message)
+          handle_error(e, context: { path: path, retries: retries })
           nil
         end
       end
 
+      def log_debug_request(path, body)
+        return unless BrainzLab::Debug.enabled?
+
+        data = if body.is_a?(Hash) && body[:traces]
+                 { count: body[:traces].size }
+               elsif body.is_a?(Hash) && body[:name]
+                 { name: body[:name] }
+               else
+                 {}
+               end
+
+        BrainzLab::Debug.log_request(:pulse, 'POST', path, data: data)
+      end
+
+      def log_debug_response(status, duration_ms, error: nil)
+        return unless BrainzLab::Debug.enabled?
+
+        BrainzLab::Debug.log_response(:pulse, status, duration_ms, error: error)
+      end
+
+      def invoke_on_send(service, method, path, payload)
+        return unless @config.on_send
+
+        @config.on_send.call(service, method, path, payload)
+      rescue StandardError => e
+        # Don't let callback errors break the SDK
+        log_error("on_send callback error: #{e.message}")
+      end
+
+      def handle_error(error, context: {})
+        log_error("#{error.message}")
+
+        # Call on_error callback if configured
+        return unless @config.on_error
+
+        @config.on_error.call(error, context.merge(service: :pulse))
+      rescue StandardError => e
+        # Don't let callback errors break the SDK
+        log_error("on_error callback error: #{e.message}")
+      end
+
       def log_error(message)
+        BrainzLab::Debug.log(message, level: :error) if BrainzLab::Debug.enabled?
+
         return unless @config.logger
 
         @config.logger.error("[BrainzLab::Pulse] #{message}")

data/lib/brainzlab/pulse.rb

@@ -47,10 +47,17 @@ module BrainzLab
       def record_trace(name, started_at:, ended_at:, kind: 'request', **attributes)
         return unless enabled?
 
+        payload = build_trace_payload(name, kind, started_at, ended_at, attributes)
+
+        # In development mode, log locally instead of sending to server
+        if BrainzLab.configuration.development_mode?
+          Development.record(service: :pulse, event_type: 'trace', payload: payload)
+          return
+        end
+
         ensure_provisioned!
         return unless BrainzLab.configuration.pulse_valid?
 
-        payload = build_trace_payload(name, kind, started_at, ended_at, attributes)
         client.send_trace(payload)
       end
 
@@ -58,9 +65,6 @@ module BrainzLab
       def record_metric(name, value:, kind: 'gauge', tags: {})
         return unless enabled?
 
-        ensure_provisioned!
-        return unless BrainzLab.configuration.pulse_valid?
-
         payload = {
           name: name,
           value: value,
@@ -69,7 +73,22 @@ module BrainzLab
           tags: tags
         }
 
-        client.send_metric(payload)
+        # In development mode, log locally instead of sending to server
+        if BrainzLab.configuration.development_mode?
+          Development.record(service: :pulse, event_type: 'metric', payload: payload)
+          return
+        end
+
+        ensure_provisioned!
+        return unless BrainzLab.configuration.pulse_valid?
+
+        if BrainzLab.instrumenting?
+          # During instrumentation, send in background thread to avoid
+          # blocking the host app with synchronous HTTP
+          Thread.new { client.send_metric(payload) }
+        else
+          client.send_metric(payload)
+        end
       end
 
       # Convenience methods for metrics

data/lib/brainzlab/rails/log_formatter.rb

@@ -641,7 +641,7 @@ module BrainzLab
       end
 
       def hash_like?(obj)
-        obj.is_a?(Hash) || (obj.respond_to?(:to_h) && obj.respond_to?(:each))
+        obj.is_a?(Hash) || (!obj.is_a?(Array) && obj.respond_to?(:to_h) && obj.respond_to?(:each))
       end
 
       def format_params_toml(params, prefix = '', depth = 0)

data/lib/brainzlab/rails/railtie.rb

@@ -55,6 +55,12 @@ module BrainzLab
       end
 
       config.after_initialize do
+        # Skip all SDK initialization if disabled
+        unless BrainzLab.configuration.enabled?
+          BrainzLab.debug_log('[Railtie] SDK disabled via BRAINZLAB_SDK_ENABLED=false, skipping initialization')
+          next
+        end
+
         # Set up custom log formatter
         BrainzLab::Rails::Railtie.setup_log_formatter if BrainzLab.configuration.log_formatter_enabled
 
@@ -114,8 +120,13 @@ module BrainzLab
         end
 
         def silence_rails_logging
-          # Create a null logger that discards all output
-          null_logger = Logger.new(File::NULL)
+          # Create a null logger that discards all output.
+          # Use ActiveSupport::Logger (not a plain ::Logger) so the logger
+          # retains LoggerSilence#silence — SolidQueue's poller calls
+          # `ActiveRecord::Base.logger.silence { ... }` every cycle, and a
+          # plain Logger lacks `silence` (NoMethodError → workers crash-loop).
+          logger_class = defined?(ActiveSupport::Logger) ? ActiveSupport::Logger : Logger
+          null_logger = logger_class.new(File::NULL)
           null_logger.level = Logger::FATAL
 
           # Silence ActiveRecord SQL logging
@@ -217,7 +228,11 @@ module BrainzLab
         context.request_method = request.request_method
         context.request_path = request.path
         context.request_url = request.url
-        context.request_params = filter_params(request.params.to_h)
+        context.request_params = begin
+          filter_params(request.params.to_h)
+        rescue ActionDispatch::Http::Parameters::ParseError
+          {}
+        end
         context.request_headers = extract_headers(env)
 
         # Add breadcrumb for request start

data/lib/brainzlab/recall/buffer.rb

@@ -19,7 +19,9 @@ module BrainzLab
 
       def push(log_entry)
         @buffer.push(log_entry)
-        flush if @buffer.size >= @config.recall_buffer_size
+        # Skip synchronous flush during instrumentation to avoid blocking the host app.
+        # The background flush thread will send these entries within recall_flush_interval seconds.
+        flush if @buffer.size >= @config.recall_buffer_size && !BrainzLab.instrumenting?
       end
 
       def flush

data/lib/brainzlab/recall/client.rb

@@ -32,20 +32,29 @@ module BrainzLab
 
       def post(path, body)
         uri = URI.join(@config.recall_url, path)
+
+        # Call on_send callback if configured
+        invoke_on_send(:recall, :post, path, body)
+
+        # Log debug output for request
+        log_debug_request(path, body)
+
         request = Net::HTTP::Post.new(uri)
         request['Content-Type'] = 'application/json'
         request['Authorization'] = "Bearer #{@config.secret_key}"
         request['User-Agent'] = "brainzlab-sdk-ruby/#{BrainzLab::VERSION}"
         request.body = JSON.generate(body)
 
-        execute_with_retry(uri, request)
+        execute_with_retry(uri, request, path)
       rescue StandardError => e
-        log_error("Failed to send to Recall: #{e.message}")
+        handle_error(e, context: { path: path, body_size: body.to_s.length })
         nil
       end
 
-      def execute_with_retry(uri, request)
+      def execute_with_retry(uri, request, path)
         retries = 0
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         begin
           http = Net::HTTP.new(uri.host, uri.port)
           http.use_ssl = uri.scheme == 'https'
@@ -53,6 +62,10 @@ module BrainzLab
           http.read_timeout = 10
 
           response = http.request(request)
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+
+          # Log debug output for response
+          log_debug_response(response.code.to_i, duration_ms)
 
           case response.code.to_i
           when 200..299
@@ -64,7 +77,10 @@ module BrainzLab
           when 429, 500..599
             raise RetryableError, "Server error: #{response.code}"
           else
-            log_error("Recall API error: #{response.code} - #{response.body}")
+            handle_error(
+              StandardError.new("Recall API error: #{response.code}"),
+              context: { path: path, status: response.code, body: response.body }
+            )
             nil
           end
         rescue RetryableError, Net::OpenTimeout, Net::ReadTimeout => e
@@ -73,15 +89,67 @@ module BrainzLab
             sleep(RETRY_DELAY * retries)
             retry
           end
-          log_error("Failed after #{MAX_RETRIES} retries: #{e.message}")
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+          log_debug_response(0, duration_ms, error: e.message)
+          handle_error(e, context: { path: path, retries: retries })
           nil
         end
       end
 
+      def log_debug_request(path, body)
+        return unless BrainzLab::Debug.enabled?
+
+        data = if body.is_a?(Hash) && body[:logs]
+                 { count: body[:logs].size }
+               elsif body.is_a?(Hash) && body[:message]
+                 { message: body[:message] }
+               else
+                 {}
+               end
+
+        BrainzLab::Debug.log_request(:recall, 'POST', path, data: data)
+      end
+
+      def log_debug_response(status, duration_ms, error: nil)
+        return unless BrainzLab::Debug.enabled?
+
+        BrainzLab::Debug.log_response(:recall, status, duration_ms, error: error)
+      end
+
+      def invoke_on_send(service, method, path, payload)
+        return unless @config.on_send
+
+        @config.on_send.call(service, method, path, payload)
+      rescue StandardError => e
+        # Don't let callback errors break the SDK
+        log_error("on_send callback error: #{e.message}")
+      end
+
+      def handle_error(error, context: {})
+        # Wrap the error in a structured error if it's not already one
+        structured_error = if error.is_a?(BrainzLab::Error)
+                             error
+                           else
+                             ErrorHandler.wrap(error, service: 'Recall', operation: context[:path] || 'unknown')
+                           end
+
+        log_error(structured_error.message)
+
+        # Call on_error callback if configured
+        return unless @config.on_error
+
+        @config.on_error.call(structured_error, context.merge(service: :recall))
+      rescue StandardError => e
+        # Don't let callback errors break the SDK
+        log_error("on_error callback error: #{e.message}")
+      end
+
       def log_error(message)
+        BrainzLab::Debug.log(message, level: :error) if BrainzLab::Debug.enabled?
+
         return unless @config.logger
 
-        @config.logger.error("[BrainzLab] #{message}")
+        @config.logger.error("[BrainzLab::Recall] #{message}")
       end
 
       class RetryableError < StandardError; end