brainzlab 0.1.11 → 0.1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49af0bcd7ebaf8cc4b66040ae38be6eb6e8826178e493283b9241083ef54b79f
-  data.tar.gz: '0057911ea7e6c7113e06a148863dc7e806e7af32f0bd9eb6f579bb7b69377849'
+  metadata.gz: ac1922e302a243a61b38d955da04782ae4e66c11908bea728a39b6ad3c68634e
+  data.tar.gz: 748d7f686bf204d0e0ef9322fb445dd75b62c13404472758631e976cc135c295
 SHA512:
-  metadata.gz: 91b591d98847edc9f401e6f505df003a1a802319db212615dab3a33a09fd320cde743c9c0dac40717dade391434a127ffa0975b28ec903f07a3907ab3f78f8fd
-  data.tar.gz: a9f1105138dc3a9871854e9a6526381950b66c0f2d4e18dcc40b2f434cb55d7f7af3bd2a27933401fa4ebb1b658d68fcf420b3476ebbea7a15944d543c16ab76
+  metadata.gz: ee4bdba72d0fed3db7489bf0335de8dd4b8139a941eb381b4a35a3425ca0fa7755f3702869ac93405a5cd0e9def39174ced81eb559c3de99b6970e353c99f977
+  data.tar.gz: 8aec3a840b93948c73ad1e1e518182b316b4a8a29c20c8b5a6819a88c5f12e647d9c576dc865e04991ac0ea4976e2536d21751b1291ebbaf5594713a9317b2b7

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.13] - 2026-02-24
+
+### Fixed
+
+- **Rails LogFormatter** - Fix `TypeError: wrong element type Hash at 0 (expected array)` in `format_params_toml`
+  - `hash_like?` incorrectly matched Arrays (they respond to `to_h` and `each`), causing `Array#to_h` to fail when params contained arrays of hashes
+
 ## [0.1.1] - 2025-12-23
 
 ### Fixed

data/README.md

@@ -298,6 +298,8 @@ end
 | `BRAINZLAB_SERVICE` | Service name |
 | `BRAINZLAB_APP_NAME` | App name for auto-provisioning |
 | `BRAINZLAB_DEBUG` | Enable debug logging (`true`/`false`) |
+| `BRAINZLAB_MODE` | SDK mode: `production` (default) or `development` (offline) |
+| `BRAINZLAB_DEV_DB_PATH` | SQLite database path for development mode |
 | `RECALL_URL` | Custom Recall endpoint |
 | `REFLEX_URL` | Custom Reflex endpoint |
 | `PULSE_URL` | Custom Pulse endpoint |
@@ -312,13 +314,218 @@ config.scrub_fields = [:password, :password_confirmation, :token, :api_key, :sec
 
 ## Debug Mode
 
-Enable debug mode to see SDK activity:
+Debug mode provides detailed visibility into SDK operations, including all API requests and responses with timing information. This is invaluable for troubleshooting integration issues.
+
+### Enabling Debug Mode
 
 ```ruby
-config.debug = true
-# Or set BRAINZLAB_DEBUG=true
+# In your initializer
+BrainzLab.configure do |config|
+  config.debug = true
+end
+
+# Or via environment variable
+# BRAINZLAB_DEBUG=true
+```
+
+### Debug Output Format
+
+When debug mode is enabled, you'll see colorized output in your terminal:
+
+```
+[BrainzLab] 12:34:56 -> Recall POST /api/v1/logs (count: 5)
+[BrainzLab] 12:34:56 <- Recall 200 OK (45ms)
+
+[BrainzLab] 12:34:57 -> Reflex POST /api/v1/errors (exception: RuntimeError)
+[BrainzLab] 12:34:57 <- Reflex 201 Created (23ms)
+
+[BrainzLab] 12:34:58 -> Pulse POST /api/v1/traces (name: GET /users)
+[BrainzLab] 12:34:58 <- Pulse 200 OK (18ms)
+```
+
+The output includes:
+- Timestamp for each operation
+- Service name (Recall, Reflex, Pulse, etc.)
+- Request method and path
+- Payload summary (log count, exception type, etc.)
+- Response status code and message
+- Request duration with color coding (green < 100ms, yellow < 1s, red > 1s)
+
+### Custom Logger
+
+You can provide your own logger to capture debug output:
+
+```ruby
+BrainzLab.configure do |config|
+  config.debug = true
+  config.logger = Rails.logger
+  # Or any Logger-compatible object
+  config.logger = Logger.new('log/brainzlab.log')
+end
 ```
 
+### Debug Callbacks
+
+For advanced debugging and monitoring, you can hook into SDK operations:
+
+```ruby
+BrainzLab.configure do |config|
+  # Called before each API request
+  config.on_send = ->(service, method, path, payload) {
+    Rails.logger.debug "[BrainzLab] Sending to #{service}: #{method} #{path}"
+
+    # You can use this to:
+    # - Log all outgoing requests
+    # - Send metrics to your monitoring system
+    # - Add custom tracing
+  }
+
+  # Called when an SDK error occurs
+  config.on_error = ->(error, context) {
+    Rails.logger.error "[BrainzLab] Error in #{context[:service]}: #{error.message}"
+
+    # You can use this to:
+    # - Alert on SDK failures
+    # - Track error rates
+    # - Fallback to alternative logging
+
+    # Note: This is for SDK errors, not application errors
+    # Application errors are sent to Reflex as normal
+  }
+end
+```
+
+### Programmatic Debug Logging
+
+You can also use the Debug module directly:
+
+```ruby
+# Log a debug message (only outputs when debug=true)
+BrainzLab::Debug.log("Custom message", level: :info)
+BrainzLab::Debug.log("Something went wrong", level: :error, error_code: 500)
+
+# Measure operation timing
+BrainzLab::Debug.measure(:custom, "expensive_operation") do
+  # Your code here
+end
+
+# Check if debug mode is enabled
+if BrainzLab::Debug.enabled?
+  # Perform additional debug operations
+end
+```
+
+### Debug Output Levels
+
+Debug messages are color-coded by level:
+- **DEBUG** (gray) - Verbose internal operations
+- **INFO** (cyan) - Normal operations
+- **WARN** (yellow) - Potential issues
+- **ERROR** (red) - Failed operations
+
+## Development Mode
+
+Development mode allows you to use the SDK without a BrainzLab server connection. Events are logged to stdout in a readable format and stored locally in a SQLite database.
+
+### Configuration
+
+```ruby
+# config/initializers/brainzlab.rb
+BrainzLab.configure do |config|
+  # Enable development mode (works offline)
+  config.mode = :development
+
+  # Optional: customize the SQLite database path (default: tmp/brainzlab.sqlite3)
+  config.development_db_path = 'tmp/brainzlab_dev.sqlite3'
+
+  # Other settings still apply
+  config.environment = Rails.env
+  config.service = 'my-app'
+end
+```
+
+Or use the environment variable:
+
+```bash
+export BRAINZLAB_MODE=development
+```
+
+### Features
+
+In development mode:
+
+- **No server connection required** - Works completely offline
+- **Stdout logging** - All events are pretty-printed to the console with colors
+- **Local storage** - Events are stored in SQLite at `tmp/brainzlab.sqlite3`
+- **Queryable** - Use `BrainzLab.development_events` to query stored events
+
+### Querying Events
+
+```ruby
+# Get all events
+events = BrainzLab.development_events
+
+# Filter by service
+logs = BrainzLab.development_events(service: :recall)
+errors = BrainzLab.development_events(service: :reflex)
+traces = BrainzLab.development_events(service: :pulse)
+
+# Filter by event type
+BrainzLab.development_events(event_type: 'log')
+BrainzLab.development_events(event_type: 'error')
+BrainzLab.development_events(event_type: 'trace')
+
+# Filter by time
+BrainzLab.development_events(since: 1.hour.ago)
+
+# Limit results
+BrainzLab.development_events(limit: 10)
+
+# Combine filters
+BrainzLab.development_events(
+  service: :recall,
+  since: 30.minutes.ago,
+  limit: 50
+)
+
+# Get stats by service
+BrainzLab.development_stats
+# => { recall: 42, reflex: 3, pulse: 15 }
+
+# Clear all stored events
+BrainzLab.clear_development_events!
+```
+
+### Console Output
+
+In development mode, events are pretty-printed to stdout:
+
+```
+[14:32:15.123] [RECALL] log [INFO] User signed up
+  user_id: 123
+  data: {email: "user@example.com"}
+
+[14:32:16.456] [REFLEX] error RuntimeError: Something went wrong
+  error_class: "RuntimeError"
+  environment: "development"
+  request_id: "abc-123"
+
+[14:32:17.789] [PULSE] trace GET /users (45.2ms)
+  request_method: "GET"
+  request_path: "/users"
+  status: 200
+  db_ms: 12.3
+```
+
+### Use Cases
+
+Development mode is useful for:
+
+- **Local development** without setting up a BrainzLab account
+- **Testing** SDK integration in CI/CD pipelines
+- **Debugging** to inspect exactly what events would be sent
+- **Offline development** when working without internet access
+
 ## Self-Hosted
 
 For self-hosted BrainzLab installations:

data/lib/brainzlab/beacon/client.rb

@@ -200,7 +200,27 @@ module BrainzLab
       end
 
       def log_error(operation, error)
-        BrainzLab.debug_log("[Beacon::Client] #{operation} failed: #{error.message}")
+        structured_error = ErrorHandler.wrap(error, service: 'Beacon', operation: operation)
+        BrainzLab.debug_log("[Beacon::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Beacon', 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: 'Beacon', operation: operation)
+        BrainzLab.debug_log("[Beacon::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Beacon', operation: operation })
+        end
+
+        structured_error
       end
     end
   end

data/lib/brainzlab/configuration.rb

@@ -7,7 +7,11 @@ module BrainzLab
     # recall_min_level has a custom setter with validation
     attr_reader :recall_min_level
 
-    attr_accessor :secret_key,
+    # mode has a custom setter with validation
+    attr_reader :mode
+
+    attr_accessor :enabled,
+                  :secret_key,
                   :environment,
                   :service,
                   :host,
@@ -106,6 +110,8 @@ module BrainzLab
                   :synapse_auto_provision,
                   :scrub_fields,
                   :logger,
+                  :on_error,
+                  :on_send,
                   :instrument_http,
                   :instrument_active_record,
                   :instrument_redis,
@@ -150,7 +156,9 @@ module BrainzLab
                   :devtools_asset_path,
                   :devtools_panel_position,
                   :devtools_expand_by_default,
-                  :rails_instrumentation_handled_externally
+                  :rails_instrumentation_handled_externally,
+                  :development_db_path,
+                  :development_log_output
 
     # Services that should not track themselves to avoid circular dependencies
     SELF_TRACKING_SERVICES = {
@@ -162,6 +170,9 @@ 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)
 
@@ -180,6 +191,13 @@ module BrainzLab
       # 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'
@@ -306,6 +324,12 @@ module BrainzLab
       # 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
@@ -363,17 +387,50 @@ module BrainzLab
 
     def recall_min_level=(level)
       level = level.to_sym
-      raise ArgumentError, "Invalid level: #{level}" unless LEVELS.include?(level)
+      unless LEVELS.include?(level)
+        raise ValidationError.new(
+          "Invalid log level: #{level}",
+          hint: "Valid log levels are: #{LEVELS.join(', ')}",
+          code: 'invalid_log_level',
+          field: 'recall_min_level',
+          context: { provided: level, valid_values: LEVELS }
+        )
+      end
 
       @recall_min_level = level
     end
 
+    MODES = %i[production development].freeze
+
+    def mode=(mode)
+      mode = mode.to_sym
+      unless MODES.include?(mode)
+        raise ValidationError.new(
+          "Invalid mode: #{mode}",
+          hint: "Valid modes are: #{MODES.join(', ')}. Use :development for offline mode with local storage.",
+          code: 'invalid_mode',
+          field: 'mode',
+          context: { provided: mode, valid_values: MODES }
+        )
+      end
+
+      @mode = mode
+    end
+
+    def development_mode?
+      @mode == :development
+    end
+
     def level_enabled?(level)
       LEVELS.index(level.to_sym) >= LEVELS.index(@recall_min_level)
     end
 
     def valid?
-      !@secret_key.nil? && !@secret_key.empty?
+      @enabled && !@secret_key.nil? && !@secret_key.empty?
+    end
+
+    def enabled?
+      @enabled == true
     end
 
     def reflex_valid?
@@ -488,8 +545,24 @@ module BrainzLab
       @debug == true
     end
 
+    # Returns hostnames of all configured SDK service URLs
+    # Used by Net::HTTP instrumentation to skip tracking SDK's own HTTP calls
+    def sdk_service_hosts
+      @sdk_service_hosts ||= begin
+        urls = [
+          @recall_url, @reflex_url, @pulse_url, @flux_url,
+          @signal_url, @vault_url, @vision_url, @cortex_url,
+          @beacon_url, @nerve_url, @dendrite_url, @sentinel_url,
+          @synapse_url
+        ].compact
+
+        urls.filter_map { |url| URI.parse(url).host rescue nil }.uniq
+      end
+    end
+
     # Check if recall is effectively enabled (considering self-tracking)
     def recall_effectively_enabled?
+      return false unless @enabled
       return false unless @recall_enabled
       return true unless @disable_self_tracking
 
@@ -500,6 +573,7 @@ module BrainzLab
 
     # Check if reflex is effectively enabled (considering self-tracking)
     def reflex_effectively_enabled?
+      return false unless @enabled
       return false unless @reflex_enabled
       return true unless @disable_self_tracking
 
@@ -510,6 +584,7 @@ module BrainzLab
 
     # Check if pulse is effectively enabled (considering self-tracking)
     def pulse_effectively_enabled?
+      return false unless @enabled
       return false unless @pulse_enabled
       return true unless @disable_self_tracking
 
@@ -520,6 +595,7 @@ module BrainzLab
 
     # Check if flux is effectively enabled (considering self-tracking)
     def flux_effectively_enabled?
+      return false unless @enabled
       return false unless @flux_enabled
       return true unless @disable_self_tracking
 
@@ -530,6 +606,7 @@ module BrainzLab
 
     # Check if signal is effectively enabled (considering self-tracking)
     def signal_effectively_enabled?
+      return false unless @enabled
       return false unless @signal_enabled
       return true unless @disable_self_tracking
 

data/lib/brainzlab/cortex/client.rb

@@ -132,7 +132,27 @@ module BrainzLab
       end
 
       def log_error(operation, error)
-        BrainzLab.debug_log("[Cortex::Client] #{operation} failed: #{error.message}")
+        structured_error = ErrorHandler.wrap(error, service: 'Cortex', operation: operation)
+        BrainzLab.debug_log("[Cortex::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Cortex', 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: 'Cortex', operation: operation)
+        BrainzLab.debug_log("[Cortex::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Cortex', operation: operation })
+        end
+
+        structured_error
       end
     end
   end