brainzlab 0.1.11 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49af0bcd7ebaf8cc4b66040ae38be6eb6e8826178e493283b9241083ef54b79f
-  data.tar.gz: '0057911ea7e6c7113e06a148863dc7e806e7af32f0bd9eb6f579bb7b69377849'
+  metadata.gz: 85a5cf3a64e256a569be39f7caa1ec6268755616ac6037db51f1543ee74dd50c
+  data.tar.gz: '09c531bb0793d26db1f62faf41f9ead294130a7036f6e5f6ab270fd8c6c46040'
 SHA512:
-  metadata.gz: 91b591d98847edc9f401e6f505df003a1a802319db212615dab3a33a09fd320cde743c9c0dac40717dade391434a127ffa0975b28ec903f07a3907ab3f78f8fd
-  data.tar.gz: a9f1105138dc3a9871854e9a6526381950b66c0f2d4e18dcc40b2f434cb55d7f7af3bd2a27933401fa4ebb1b658d68fcf420b3476ebbea7a15944d543c16ab76
+  metadata.gz: 28c2f10fc4457d4f2f34c5bcf4d63c14a062d4fcd8437b13cbcebc1a062976361b2014f5567e0fff82682a054fa83363f7e955a23d3d59ae285a9f06500c79e6
+  data.tar.gz: 5d130bf7242d57c3149803649262995daf298483c406002ab99e01495efb14df7a6874b8eb485daa90c79da8903ad37f6516ba0ca7e2c8930ff069a1b536a206

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,6 +7,9 @@ module BrainzLab
     # recall_min_level has a custom setter with validation
     attr_reader :recall_min_level
 
+    # mode has a custom setter with validation
+    attr_reader :mode
+
     attr_accessor :secret_key,
                   :environment,
                   :service,
@@ -106,6 +109,8 @@ module BrainzLab
                   :synapse_auto_provision,
                   :scrub_fields,
                   :logger,
+                  :on_error,
+                  :on_send,
                   :instrument_http,
                   :instrument_active_record,
                   :instrument_redis,
@@ -150,7 +155,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 = {
@@ -180,6 +187,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 +320,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,11 +383,40 @@ 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

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

data/lib/brainzlab/debug.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  # Debug module for SDK operation logging
+  #
+  # Provides pretty-printed debug output for all SDK operations when debug mode is enabled.
+  # Includes timing information and request/response details.
+  #
+  # @example Enable debug mode
+  #   BrainzLab.configure do |config|
+  #     config.debug = true
+  #   end
+  #
+  # @example Use custom logger
+  #   BrainzLab.configure do |config|
+  #     config.debug = true
+  #     config.logger = Logger.new(STDOUT)
+  #   end
+  #
+  # @example Manual debug logging
+  #   BrainzLab::Debug.log("Custom message", level: :info)
+  #
+  module Debug
+    COLORS = {
+      reset: "\e[0m",
+      bold: "\e[1m",
+      dim: "\e[2m",
+      red: "\e[31m",
+      green: "\e[32m",
+      yellow: "\e[33m",
+      blue: "\e[34m",
+      magenta: "\e[35m",
+      cyan: "\e[36m",
+      white: "\e[37m",
+      gray: "\e[90m"
+    }.freeze
+
+    LEVEL_COLORS = {
+      debug: :gray,
+      info: :cyan,
+      warn: :yellow,
+      error: :red,
+      fatal: :red
+    }.freeze
+
+    LEVEL_LABELS = {
+      debug: 'DEBUG',
+      info: 'INFO',
+      warn: 'WARN',
+      error: 'ERROR',
+      fatal: 'FATAL'
+    }.freeze
+
+    class << self
+      # Log a debug message if debug mode is enabled
+      #
+      # @param message [String] The message to log
+      # @param level [Symbol] Log level (:debug, :info, :warn, :error, :fatal)
+      # @param data [Hash] Optional additional data to include
+      # @return [void]
+      def log(message, level: :info, **data)
+        return unless enabled?
+
+        output = format_message(message, level: level, **data)
+        write_output(output, level: level)
+      end
+
+      # Log an outgoing request
+      #
+      # @param service [String, Symbol] The service name (e.g., :recall, :reflex)
+      # @param method [String] HTTP method
+      # @param path [String] Request path
+      # @param data [Hash] Request payload summary
+      # @return [void]
+      def log_request(service, method, path, data: nil)
+        return unless enabled?
+
+        data_summary = summarize_data(data) if data
+        message = data_summary ? "#{method} #{path} #{data_summary}" : "#{method} #{path}"
+
+        output = format_arrow_message(:out, service, message)
+        write_output(output, level: :info)
+      end
+
+      # Log an incoming response
+      #
+      # @param service [String, Symbol] The service name
+      # @param status [Integer] HTTP status code
+      # @param duration_ms [Float] Request duration in milliseconds
+      # @param error [String, nil] Error message if request failed
+      # @return [void]
+      def log_response(service, status, duration_ms, error: nil)
+        return unless enabled?
+
+        status_text = status_message(status)
+        duration_text = format_duration(duration_ms)
+
+        message = if error
+                    "#{status} #{status_text} (#{duration_text}) - #{error}"
+                  else
+                    "#{status} #{status_text} (#{duration_text})"
+                  end
+
+        level = status >= 400 ? :error : :info
+        output = format_arrow_message(:in, service, message, level: level)
+        write_output(output, level: level)
+      end
+
+      # Log an SDK operation with timing
+      #
+      # @param service [String, Symbol] The service name
+      # @param operation [String] Operation description
+      # @param data [Hash] Operation data
+      # @return [void]
+      def log_operation(service, operation, **data)
+        return unless enabled?
+
+        data_summary = data.empty? ? '' : " (#{format_data_inline(data)})"
+        message = "#{operation}#{data_summary}"
+
+        output = format_arrow_message(:out, service, message)
+        write_output(output, level: :info)
+      end
+
+      # Measure and log execution time of a block
+      #
+      # @param service [String, Symbol] The service name
+      # @param operation [String] Operation description
+      # @yield Block to measure
+      # @return [Object] Result of the block
+      def measure(service, operation)
+        return yield unless enabled?
+
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        log_operation(service, operation)
+
+        result = yield
+
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+        log("#{operation} completed", level: :debug, duration_ms: duration_ms, service: service.to_s)
+
+        result
+      rescue StandardError => e
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+        log("#{operation} failed: #{e.message}", level: :error, duration_ms: duration_ms, service: service.to_s)
+        raise
+      end
+
+      # Check if debug mode is enabled
+      #
+      # @return [Boolean]
+      def enabled?
+        BrainzLab.configuration.debug?
+      end
+
+      # Check if colorized output should be used
+      #
+      # @return [Boolean]
+      def colorize?
+        return false unless enabled?
+        return @colorize if defined?(@colorize)
+
+        @colorize = $stdout.tty?
+      end
+
+      # Reset colorize detection (useful for testing)
+      def reset_colorize!
+        remove_instance_variable(:@colorize) if defined?(@colorize)
+      end
+
+      private
+
+      def format_message(message, level:, **data)
+        timestamp = format_timestamp
+        prefix = colorize("[BrainzLab]", :bold, :blue)
+        level_badge = format_level(level)
+        data_str = data.empty? ? '' : " #{format_data(data)}"
+
+        "#{prefix} #{timestamp} #{level_badge} #{message}#{data_str}"
+      end
+
+      def format_arrow_message(direction, service, message, level: :info)
+        timestamp = format_timestamp
+        prefix = colorize("[BrainzLab]", :bold, :blue)
+        arrow = direction == :out ? colorize("->", :cyan) : colorize("<-", :green)
+        service_name = colorize(service.to_s.capitalize, :magenta)
+
+        "#{prefix} #{timestamp} #{arrow} #{service_name} #{message}"
+      end
+
+      def format_timestamp
+        time = Time.now.strftime('%H:%M:%S')
+        colorize(time, :dim)
+      end
+
+      def format_level(level)
+        label = LEVEL_LABELS[level] || level.to_s.upcase
+        color = LEVEL_COLORS[level] || :white
+        colorize("[#{label}]", color)
+      end
+
+      def format_duration(ms)
+        if ms < 1
+          colorize("#{(ms * 1000).round(0)}us", :green)
+        elsif ms < 100
+          colorize("#{ms.round(1)}ms", :green)
+        elsif ms < 1000
+          colorize("#{ms.round(0)}ms", :yellow)
+        else
+          colorize("#{(ms / 1000.0).round(2)}s", :red)
+        end
+      end
+
+      def format_data(data)
+        pairs = data.map { |k, v| "#{k}: #{format_value(v)}" }
+        colorize("(#{pairs.join(', ')})", :dim)
+      end
+
+      def format_data_inline(data)
+        data.map { |k, v| "#{k}: #{format_value(v)}" }.join(', ')
+      end
+
+      def format_value(value)
+        case value
+        when String
+          value.length > 50 ? "#{value[0..47]}..." : value
+        when Hash
+          "{#{value.keys.join(', ')}}"
+        when Array
+          "[#{value.length} items]"
+        else
+          value.to_s
+        end
+      end
+
+      def summarize_data(data)
+        return nil unless data.is_a?(Hash)
+
+        summary_parts = []
+        summary_parts << "\"#{truncate(data[:message] || data['message'], 30)}\"" if data[:message] || data['message']
+
+        other_keys = data.keys.reject { |k| %i[message timestamp level].include?(k.to_sym) }
+        if other_keys.any?
+          key_summary = other_keys.take(3).map { |k| "#{k}: #{format_value(data[k])}" }.join(', ')
+          key_summary += ", ..." if other_keys.length > 3
+          summary_parts << "(#{key_summary})"
+        end
+
+        summary_parts.join(' ')
+      end
+
+      def truncate(str, length)
+        return '' unless str
+
+        str = str.to_s
+        str.length > length ? "#{str[0..length - 4]}..." : str
+      end
+
+      def status_message(status)
+        case status
+        when 200 then 'OK'
+        when 201 then 'Created'
+        when 204 then 'No Content'
+        when 400 then 'Bad Request'
+        when 401 then 'Unauthorized'
+        when 403 then 'Forbidden'
+        when 404 then 'Not Found'
+        when 422 then 'Unprocessable Entity'
+        when 429 then 'Too Many Requests'
+        when 500 then 'Internal Server Error'
+        when 502 then 'Bad Gateway'
+        when 503 then 'Service Unavailable'
+        else ''
+        end
+      end
+
+      def colorize(text, *colors)
+        return text unless colorize?
+
+        color_codes = colors.map { |c| COLORS[c] }.compact.join
+        "#{color_codes}#{text}#{COLORS[:reset]}"
+      end
+
+      def write_output(output, level:)
+        config = BrainzLab.configuration
+
+        if config.logger
+          case level
+          when :debug then config.logger.debug(strip_colors(output))
+          when :info then config.logger.info(strip_colors(output))
+          when :warn then config.logger.warn(strip_colors(output))
+          when :error, :fatal then config.logger.error(strip_colors(output))
+          else config.logger.info(strip_colors(output))
+          end
+        else
+          $stderr.puts output
+        end
+      end
+
+      def strip_colors(text)
+        text.gsub(/\e\[\d+m/, '')
+      end
+    end
+  end
+end