ez_logs_agent 0.1.3

data/lib/ez_logs_agent/sanitizer.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module EzLogsAgent
+  # Canonical sanitizer for "user-supplied data we're about to ship over
+  # the wire": HTTP params, GraphQL variables, and ActiveJob/Sidekiq
+  # arguments.
+  #
+  # Rules:
+  # - Sensitive keys (password / token / secret / api_key / credit_card,
+  #   plus user-configured patterns) are replaced with "[FILTERED]".
+  # - Nested objects recurse up to MAX_NESTING_DEPTH (3); anything deeper
+  #   collapses to "[Object]" so we never serialize unbounded graphs.
+  # - Arrays: small primitive arrays pass through; large ones (>5)
+  #   collapse to a preview-plus-count string; arrays of objects are
+  #   sanitized element-by-element with the same depth budget.
+  # - Non-primitive Ruby objects (anything not String/Numeric/Bool/nil)
+  #   become "[Object]". This protects us from accidentally serializing
+  #   ActiveRecord instances or other big graphs that found their way
+  #   into a job argument.
+  #
+  # The module is pure (no I/O, no state), so it's safe to call from
+  # any thread.
+  module Sanitizer
+    # Default sensitive-key patterns. Matched case-insensitively as
+    # SUBSTRINGS of the key, so `customer_password` matches `password`.
+    SENSITIVE_PATTERNS = %w[
+      password passwd pwd
+      token access_token refresh_token api_token auth_token
+      secret api_secret client_secret
+      api_key apikey private_key privatekey secret_key secretkey
+      credential auth authorization
+      encrypted encrypted_data
+      ssn social_security
+      credit_card card_number cvv cvc
+    ].freeze
+
+    # Hard ceiling for nested object recursion. Deeper structures
+    # collapse to the literal string "[Object]".
+    MAX_NESTING_DEPTH = 3
+
+    # Threshold above which an array is summarized instead of inlined.
+    # Below this size, primitive arrays are shipped verbatim; arrays
+    # of objects are mapped element-by-element.
+    MAX_ARRAY_DISPLAY_SIZE = 5
+
+    class << self
+      # Sanitize a single key/value pair. Public entry point used by
+      # HTTP-param and job-arg sanitization.
+      #
+      # @param key [String, Symbol] Variable / parameter name.
+      # @param value [Object] Variable / parameter value.
+      # @param depth [Integer] Current recursion depth.
+      # @return [Object] Sanitized value (may be the original primitive).
+      def sanitize_value(key, value, depth = 0)
+        return "[FILTERED]" if sensitive_key?(key)
+        return sanitize_nested_object(value, depth) if value.is_a?(Hash)
+        return sanitize_array_value(value, depth) if value.is_a?(Array)
+        return value if primitive?(value)
+
+        # Anything else (AR records, dates, custom objects) collapses to
+        # a placeholder so we never accidentally serialize a huge graph.
+        "[Object]"
+      end
+
+      # Sanitize an ordered list of job arguments (positional). Returns
+      # an Array with each element sanitized as if its index were the
+      # key (no sensitive-key match for integers — only the nested
+      # structure matters at the top level).
+      #
+      # @param args [Array] Job arguments array.
+      # @return [Array] Sanitized arguments array.
+      def sanitize_args(args)
+        return [] unless args.is_a?(Array)
+
+        # Top-level array uses the same array-rules so giant arg lists
+        # truncate to a preview-with-count rather than ship verbatim.
+        sanitize_array_value(args, 0)
+      end
+
+      # Check whether a key matches a sensitive pattern. Public so the
+      # HTTP middleware can short-circuit early on identical keys.
+      #
+      # @param key [String, Symbol]
+      # @return [Boolean]
+      def sensitive_key?(key)
+        key_lower = key.to_s.downcase
+        return true if SENSITIVE_PATTERNS.any? { |pattern| key_lower.include?(pattern) }
+
+        user_patterns = EzLogsAgent.configuration.excluded_graphql_variable_keys || []
+        user_patterns.any? { |pattern| key_lower.include?(pattern.to_s.downcase) }
+      rescue
+        # Defensive: when in doubt, treat as sensitive.
+        true
+      end
+
+      private
+
+      def sanitize_nested_object(hash, depth)
+        return "[Object]" if depth >= MAX_NESTING_DEPTH
+        return {} if hash.empty?
+
+        hash.each_with_object({}) do |(key, value), result|
+          result[key] = sanitize_value(key, value, depth + 1)
+        end
+      end
+
+      def sanitize_array_value(array, depth)
+        return [] if array.empty?
+
+        all_primitives = array.all? { |item| primitive?(item) }
+
+        if all_primitives
+          if array.size <= MAX_ARRAY_DISPLAY_SIZE
+            array
+          else
+            preview = array.first(MAX_ARRAY_DISPLAY_SIZE)
+            "#{preview}... (#{array.size} total)"
+          end
+        else
+          if array.size <= MAX_ARRAY_DISPLAY_SIZE
+            array.map { |item| sanitize_array_item(item, depth) }
+          else
+            preview = array.first(MAX_ARRAY_DISPLAY_SIZE).map { |item| sanitize_array_item(item, depth) }
+            { "_truncated" => true, "_count" => array.size, "_preview" => preview }
+          end
+        end
+      end
+
+      def sanitize_array_item(item, depth)
+        if primitive?(item)
+          item
+        elsif item.is_a?(Hash)
+          sanitize_nested_object(item, depth + 1)
+        elsif item.is_a?(Array)
+          sanitize_array_value(item, depth + 1)
+        else
+          "[Object]"
+        end
+      end
+
+      def primitive?(value)
+        value.nil? ||
+          value.is_a?(String) ||
+          value.is_a?(Numeric) ||
+          value.is_a?(TrueClass) ||
+          value.is_a?(FalseClass)
+      end
+    end
+  end
+end

data/lib/ez_logs_agent/transport.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module EzLogsAgent
+  # HTTP Transport Client
+  #
+  # Lowest-level component that sends events to the EzLogs server.
+  # Performs a single HTTP POST request with no retries or backoff.
+  #
+  # Responsibilities:
+  # - Serialize events to JSON
+  # - POST to server endpoint
+  # - Return :success or :failure
+  #
+  # Does NOT:
+  # - Retry failed requests
+  # - Implement backoff logic
+  # - Read from Buffer
+  # - Call Buffer.flush
+  # - Raise exceptions to host app
+  class Transport
+    class << self
+      # Send events to the server
+      #
+      # @param events [Array<Hash>] Array of event hashes
+      # @return [Symbol] :success if 2xx response, :failure otherwise
+      def send(events)
+        return :success if events.nil? || events.empty?
+
+        response = post_events(events)
+        classify_response(response)
+      rescue => error
+        Logger.error("[Transport] send failed: #{error.class} - #{error.message}")
+        :failure
+      end
+
+      private
+
+      def post_events(events)
+        uri = build_uri
+        http = build_http_client(uri)
+        request = build_request(uri, events)
+
+        http.request(request)
+      end
+
+      def build_uri
+        server_url = EzLogsAgent.configuration.server_url
+        raise "server_url not configured" if server_url.nil? || server_url.empty?
+
+        URI.parse("#{server_url}/api/events")
+      rescue => error
+        raise "Invalid server_url: #{error.message}"
+      end
+
+      def build_http_client(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = 5
+        http.read_timeout = 10
+        http
+      end
+
+      def build_request(uri, events)
+        request = Net::HTTP::Post.new(uri.path)
+        request["Content-Type"] = "application/json"
+
+        token = EzLogsAgent.configuration.project_token
+        request["Authorization"] = "Bearer #{token}" if token
+
+        request.body = JSON.generate({ events: events })
+        request
+      end
+
+      def classify_response(response)
+        status = response.code.to_i
+
+        if status >= 200 && status < 300
+          Logger.debug("[Transport] send succeeded (#{status})")
+          :success
+        else
+          Logger.error("[Transport] send failed (#{status})")
+          :failure
+        end
+      end
+    end
+  end
+end

data/lib/ez_logs_agent/user_agent_detector.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module EzLogsAgent
+  # Detects whether an HTTP request originated from an AI agent client
+  # (Claude Desktop, ChatGPT, Cursor, Windsurf, …) by inspecting the
+  # User-Agent string.
+  #
+  # Behavior is intentionally narrow: returns vendor metadata only when
+  # the UA starts with one of the known LLM-client prefixes. Anything
+  # else returns nil — we never *infer* agency from weak signals.
+  #
+  # The Next.js agent ships an identical detector
+  # (`src/user-agent-detector.ts`) so both wire-format emitters classify
+  # the same UA the same way.
+  module UserAgentDetector
+    # Patterns are matched case-insensitively against the start of the
+    # User-Agent string. New vendors must be added in BOTH agents.
+    PATTERNS = [
+      { prefix: "claude-",     vendor: "claude",     label: "Claude" },
+      { prefix: "anthropic-",  vendor: "claude",     label: "Claude" },
+      { prefix: "gpt-",        vendor: "openai",     label: "ChatGPT" },
+      { prefix: "chatgpt-",    vendor: "openai",     label: "ChatGPT" },
+      { prefix: "openai-",     vendor: "openai",     label: "ChatGPT" },
+      { prefix: "cursor-",     vendor: "cursor",     label: "Cursor" },
+      { prefix: "windsurf-",   vendor: "windsurf",   label: "Windsurf" }
+    ].freeze
+
+    # Classify a User-Agent string.
+    #
+    # @param user_agent [String, nil] Raw User-Agent header value.
+    # @return [Hash, nil] `{ kind: "agent", vendor:, label:, suggested_id: }`
+    #   when the UA matches a known LLM client; nil otherwise.
+    def self.classify(user_agent)
+      return nil if user_agent.nil? || user_agent.empty?
+
+      ua = user_agent.downcase
+      match = PATTERNS.find { |p| ua.start_with?(p[:prefix]) }
+      return nil unless match
+
+      {
+        kind: "agent",
+        vendor: match[:vendor],
+        label: match[:label],
+        suggested_id: "agent:#{match[:vendor]}"
+      }
+    rescue
+      # Defensive: classifier must never crash the middleware.
+      nil
+    end
+  end
+end

data/lib/ez_logs_agent/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EzLogsAgent
+  VERSION = "0.1.3"
+end

data/lib/ez_logs_agent.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "ez_logs_agent/version"
+require_relative "ez_logs_agent/configuration"
+require_relative "ez_logs_agent/configuration_validator"
+require_relative "ez_logs_agent/logger"
+require_relative "ez_logs_agent/correlation"
+require_relative "ez_logs_agent/actor_validator"
+require_relative "ez_logs_agent/actor"
+require_relative "ez_logs_agent/user_agent_detector"
+require_relative "ez_logs_agent/sanitizer"
+require_relative "ez_logs_agent/event_builder"
+require_relative "ez_logs_agent/resource_extractor"
+require_relative "ez_logs_agent/buffer"
+require_relative "ez_logs_agent/transport"
+require_relative "ez_logs_agent/retry_sender"
+require_relative "ez_logs_agent/flush_scheduler"
+require_relative "ez_logs_agent/middleware/http_request"
+require_relative "ez_logs_agent/capturers/job_capturer"
+require_relative "ez_logs_agent/capturers/active_job_capturer"
+require_relative "ez_logs_agent/capturers/database_capturer"
+
+# Load Railtie only when Rails is present
+require_relative "ez_logs_agent/railtie" if defined?(Rails::Railtie)
+
+module EzLogsAgent
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/generators/ez_logs_agent/install/install_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module EzLogsAgent
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an EzLogsAgent initializer with all configuration options"
+
+      def show_welcome_message
+        say "\n"
+        say "=" * 70, :green
+        say "  EzLogs Agent Installation", :green
+        say "=" * 70, :green
+        say "\n"
+      end
+
+      def detect_environment
+        @sidekiq_detected = defined?(Sidekiq)
+        @activejob_detected = defined?(ActiveJob)
+        @activerecord_detected = defined?(ActiveRecord)
+        @devise_detected = defined?(Devise)
+
+        say "Detected Components:", :cyan
+        rails_version = defined?(Rails::VERSION::STRING) ? Rails::VERSION::STRING : "unknown"
+        say "  • Rails #{rails_version}"
+        say "  • Sidekiq #{Sidekiq::VERSION}", :green if @sidekiq_detected
+        say "  • ActiveJob", :green if @activejob_detected && !@sidekiq_detected
+        say "  • ActiveRecord", :green if @activerecord_detected
+        say "  • Devise", :green if @devise_detected
+        say "\n"
+      end
+
+      def create_initializer_file
+        initializer_path = File.join(destination_root, "config/initializers/ez_logs_agent.rb")
+
+        if File.exist?(initializer_path)
+          say "⚠️  Initializer already exists at config/initializers/ez_logs_agent.rb", :yellow
+          say "   Skipping creation to avoid overwriting your existing configuration.", :yellow
+          say "\n"
+          return
+        end
+
+        template "ez_logs_agent.rb.tt", "config/initializers/ez_logs_agent.rb"
+        say "\n"
+        say "✅ Created config/initializers/ez_logs_agent.rb", :green
+        say "\n"
+      end
+
+      def show_next_steps
+        say "=" * 70, :cyan
+        say "  Next Steps", :cyan
+        say "=" * 70, :cyan
+        say "\n"
+
+        say "1. Get your API key from EzLogs:", :bold
+        say "   → Log in to your EzLogs dashboard"
+        say "   → Go to Settings → API Keys"
+        say "   → Create a new API key for this application\n\n"
+
+        say "2. Configure the agent:", :bold
+        say "   → Open config/initializers/ez_logs_agent.rb"
+        say "   → Set your server_url (e.g., https://app.ezlogs.io)"
+        say "   → Set your project_token (the API key from step 1)\n\n"
+
+        if @devise_detected
+          say "3. Enable actor tracking (optional but recommended):", :bold
+          say "   → Uncomment the actor_from_request block"
+          say "   → The Devise example is already configured for you\n\n"
+        else
+          say "3. Enable actor tracking (optional):", :bold
+          say "   → Uncomment the actor_from_request block in the initializer"
+          say "   → Customize it for your authentication system\n\n"
+        end
+
+        say "4. Test the connection:", :bold
+        say "   → Run: rails ez_logs_agent:test_connection"
+        say "   → This verifies your configuration is correct\n\n"
+
+        say "5. Restart your Rails server:", :bold
+        say "   → The agent will start capturing events automatically"
+        say "   → Check your EzLogs dashboard to see activity\n\n"
+
+        say "=" * 70, :cyan
+        say "\n"
+
+        say "Need help? Check the README or visit https://docs.ezlogs.io", :cyan
+        say "\n"
+      end
+    end
+  end
+end

data/lib/generators/ez_logs_agent/install/templates/ez_logs_agent.rb.tt

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# EzLogsAgent Configuration
+#
+# All options below show their default values.
+# Uncomment and change only the options you need to customize.
+
+EzLogsAgent.configure do |config|
+  # =============================================================================
+  # REQUIRED SETTINGS
+  # =============================================================================
+
+  # URL of the EzLogs server (required)
+  # Default: nil (must be set for events to be sent)
+  # config.server_url = "https://your-ezlogs-server.com"
+
+  # API key for authentication (required)
+  # Get this from your EzLogs dashboard: Settings → API Keys
+  # Default: nil
+  # config.project_token = "your-api-key-here"
+
+  # =============================================================================
+  # CAPTURE SETTINGS
+  # =============================================================================
+
+  # Capture HTTP requests
+  # Default: true
+  # config.capture_http = true
+
+  # Capture background jobs (Sidekiq/ActiveJob)
+  # Default: true
+  # config.capture_jobs = true
+
+  # Capture database changes via model callbacks
+  # Default: true
+  # config.capture_database = true
+
+  # =============================================================================
+  # EXCLUSIONS
+  # =============================================================================
+
+  # Additional paths to exclude from HTTP capture (added to built-in defaults)
+  # Built-in: /rails/active_storage*, /assets*, /packs*, /vite*, /health*, /up, /favicon.ico
+  # config.excluded_paths = ["/admin*", "/internal*"]
+
+  # Additional tables to exclude from database capture (added to built-in defaults)
+  # Built-in: schema_migrations, ar_internal_metadata, sessions, session, active_storage_*, solid_queue_*, etc.
+  # config.excluded_tables = ["audit_logs", "versions"]
+
+  # Additional job classes to exclude from background job capture (added to built-in defaults)
+  # Built-in: SidekiqAlive::Worker, SolidQueue::CleanupJob, SolidQueue::RecurringJob
+  # config.excluded_job_classes = ["MyApp::HealthCheckJob", "MyApp::MetricsJob"]
+
+  # Additional GraphQL operations to exclude from capture (added to built-in defaults)
+  # Built-in: IntrospectionQuery, __* (all introspection fields like __schema, __type)
+  # Supports exact match and prefix match (patterns ending with *)
+  # config.excluded_graphql_operations = ["GetCurrentUser", "Internal*"]
+
+  # =============================================================================
+  # PERFORMANCE & RELIABILITY
+  # =============================================================================
+
+  # Max events in memory before oldest are dropped
+  # Default: 10000 (optimized for high-volume workloads)
+  # config.buffer_size = 10000
+
+  # Retry attempts for failed sends
+  # Default: 3
+  # config.retry_attempts = 3
+
+  # Seconds between automatic flushes
+  # Default: 3 (more frequent sends for better throughput)
+  # config.send_interval = 3
+
+  # =============================================================================
+  # LOGGING
+  # =============================================================================
+
+  # Agent log level (:debug, :info, :warn, :error)
+  # Default: :warn
+  # Set to :error in production to minimize output
+  # config.log_level = :warn
+
+  # =============================================================================
+  # DISPLAY NAMES (What Resource Was Affected?)
+  # =============================================================================
+
+  # Configure display name resolution per model
+  # When a database callback fires, the agent resolves a human-readable name
+  # for the affected record using the configured field.
+  #
+  # Fallback chain: configured field → name → title → number → nil
+  #
+  # Example:
+  # config.display_name_for = {
+  #   "User" => :email,    # Use email field for User models
+  #   "Product" => :name,  # Use name field for Product models
+  #   "Order" => :number   # Use number field for Order models
+  # }
+  #
+  # This enables action titles like:
+  # - "User updated 'john@example.com'" instead of just "User updated"
+  # - "Product created 'Premium Widget'" instead of just "Product created"
+  #
+  # IMPORTANT: Only use direct attributes, not associations (would trigger DB queries)
+
+  # =============================================================================
+  # ACTOR CONTEXT (Who Triggered This?)
+  # =============================================================================
+
+  # Optional: Extract actor (user identity) from HTTP requests
+  # This enables "who triggered this action?" tracking in EzLogs
+  #
+  # The hook receives (env, controller) and should return:
+  #   { id: String, label: String } or nil if actor cannot be determined
+  #
+  # Example for Devise:
+  # config.actor_from_request = ->(env, controller) {
+  #   return nil unless controller.respond_to?(:current_user)
+  #   user = controller.current_user
+  #   return nil unless user
+  #
+  #   {
+  #     id: user.id.to_s,
+  #     label: user.email
+  #   }
+  # }
+end

data/lib/tasks/ez_logs_agent.rake

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+namespace :ez_logs_agent do
+  desc "Test connection to EzLogs server"
+  task test_connection: :environment do
+    require "ez_logs_agent"
+
+    puts "\n🔍 EzLogs Agent Connection Test\n\n"
+
+    # Step 1: Validate configuration
+    puts "Step 1: Validating configuration..."
+    result = EzLogsAgent::ConfigurationValidator.validate(EzLogsAgent.configuration)
+
+    if result.errors.any?
+      puts "❌ Configuration validation failed:\n"
+      result.errors.each do |error|
+        puts "  - #{error}"
+      end
+      puts "\n"
+      exit 1
+    end
+
+    if result.warnings.any?
+      puts "⚠️  Configuration warnings:\n"
+      result.warnings.each do |warning|
+        puts "  - #{warning}"
+      end
+      puts "\n"
+    end
+
+    puts "✅ Configuration is valid\n\n"
+
+    # Step 2: Show configuration summary
+    config = EzLogsAgent.configuration
+    puts "Configuration Summary:"
+    puts "  Server URL: #{config.server_url}"
+    puts "  Project Token: #{config.project_token ? '***' + config.project_token[-4..-1] : '(not set)'}"
+    puts "  Capture HTTP: #{config.capture_http}"
+    puts "  Capture Jobs: #{config.capture_jobs}"
+    puts "  Capture Database: #{config.capture_database}"
+    puts "\n"
+
+    # Step 2: Test connection
+    puts "Step 2: Testing connection to server..."
+
+    begin
+      uri = URI.parse(config.server_url)
+      uri.path = "/api/events" if uri.path.empty?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 5
+      http.read_timeout = 10
+
+      # Send a test event
+      test_event = {
+        kind: "test",
+        correlation_id: "test_connection_#{Time.now.to_i}",
+        occurred_at: Time.now.utc.iso8601(3),
+        context: {
+          message: "EzLogs Agent connection test",
+          source: "rake ez_logs_agent:test_connection"
+        }
+      }
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{config.project_token}" if config.project_token
+      request.body = { events: [test_event] }.to_json
+
+      response = http.request(request)
+
+      case response.code.to_i
+      when 200..299
+        puts "✅ Connection successful (HTTP #{response.code})"
+        puts "   Test event accepted by server\n\n"
+        puts "✅ All checks passed! EzLogs Agent is configured correctly.\n\n"
+        exit 0
+      when 401
+        puts "❌ Authentication failed (HTTP 401)"
+        puts "   Check your project_token in config/initializers/ez_logs_agent.rb\n\n"
+        exit 1
+      when 404
+        puts "❌ Server endpoint not found (HTTP 404)"
+        puts "   Check your server_url: #{config.server_url}\n\n"
+        exit 1
+      else
+        puts "❌ Server responded with HTTP #{response.code}"
+        puts "   Response: #{response.body[0..200]}\n\n"
+        exit 1
+      end
+    rescue SocketError => e
+      puts "❌ Could not resolve host: #{e.message}"
+      puts "   Check your server_url: #{config.server_url}\n\n"
+      exit 1
+    rescue Errno::ECONNREFUSED => e
+      puts "❌ Connection refused: #{e.message}"
+      puts "   Is the EzLogs server running at #{config.server_url}?\n\n"
+      exit 1
+    rescue Timeout::Error => e
+      puts "❌ Connection timeout: #{e.message}"
+      puts "   The server is not responding. Check firewall rules.\n\n"
+      exit 1
+    rescue StandardError => e
+      puts "❌ Connection failed: #{e.class} - #{e.message}"
+      puts "   #{e.backtrace.first}\n\n"
+      exit 1
+    end
+  end
+end