ez_logs_agent 0.1.0

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/version.rb

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

data/lib/ez_logs_agent.rb

@@ -0,0 +1,42 @@
+# 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/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
+  # Default: "https://app.ezlogs.io" (the hosted EZLogs service)
+  # config.server_url = "https://app.ezlogs.io"
+
+  # 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

data/script/publish-to-public.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+#
+# publish-to-public.sh — sync the Ruby agent from the private monorepo into
+# the public `dezsirazvan/ez_logs_agent` repo, so RubyGems metadata links,
+# GitHub badges, and external contributors all resolve.
+#
+# Architecture:
+#   - This repo (ez_logs) is PRIVATE and holds the source of truth for
+#     server code, demo apps, and the agent itself.
+#   - A separate PUBLIC repo (ez_logs_agent) holds ONLY the agent so that
+#     RubyGems homepage/source/changelog URLs resolve and contributors
+#     can open issues + PRs.
+#   - This script is the seam: rsync this dir into a temp clone of the
+#     public repo, commit, push.
+#
+# Usage:
+#   ./script/publish-to-public.sh             # sync + push
+#   ./script/publish-to-public.sh --dry-run   # sync only, skip push
+#
+# Configuration:
+#   PUBLIC_REPO   — git URL. Default: https://github.com/dezsirazvan/ez_logs_agent.git
+#   PUBLIC_BRANCH — Default: master
+#
+# What gets synced:
+#   Everything in ez_logs_agent/ EXCEPT: tmp/, vendor/, .bundle/, *.gem,
+#   coverage/, .rspec_status, log/, this script's clone dir.
+#   (Tests, sig/, CHANGELOG.md, LICENSE.txt, all source — all included.)
+
+set -euo pipefail
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+AGENT_DIR="$( cd "$SCRIPT_DIR/.." && pwd )"
+REPO_ROOT="$( cd "$AGENT_DIR/.." && pwd )"
+
+PUBLIC_REPO="${PUBLIC_REPO:-https://github.com/dezsirazvan/ez_logs_agent.git}"
+PUBLIC_BRANCH="${PUBLIC_BRANCH:-master}"
+CLONE_DIR="$REPO_ROOT/.ez-logs-agent-publish"
+
+DRY_RUN=false
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+    -h|--help)
+      sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+  esac
+done
+
+echo "==> Source:  $AGENT_DIR"
+echo "==> Target:  $PUBLIC_REPO ($PUBLIC_BRANCH)"
+echo "==> Clone:   $CLONE_DIR"
+$DRY_RUN && echo "==> Mode:    DRY RUN (no push)"
+
+# ---------- Clone (or refresh) the public repo --------------------------
+if [ -d "$CLONE_DIR/.git" ]; then
+  echo "==> Refreshing existing clone..."
+  git -C "$CLONE_DIR" fetch origin
+  git -C "$CLONE_DIR" reset --hard "origin/$PUBLIC_BRANCH" 2>/dev/null || true
+else
+  echo "==> Cloning public repo..."
+  rm -rf "$CLONE_DIR"
+  git clone "$PUBLIC_REPO" "$CLONE_DIR"
+fi
+
+# Initial-commit case: empty repo with no master branch yet.
+if ! git -C "$CLONE_DIR" rev-parse --verify "$PUBLIC_BRANCH" >/dev/null 2>&1; then
+  echo "==> Public repo is empty; will create $PUBLIC_BRANCH on first push."
+  git -C "$CLONE_DIR" checkout -b "$PUBLIC_BRANCH"
+fi
+
+# ---------- Wipe the clone (except .git) and sync source ----------------
+echo "==> Syncing source into clone..."
+find "$CLONE_DIR" -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
+
+rsync -a \
+  --exclude='/tmp/' \
+  --exclude='/vendor/' \
+  --exclude='/.bundle/' \
+  --exclude='/coverage/' \
+  --exclude='/log/' \
+  --exclude='/script/publish-to-public.sh' \
+  --exclude='.rspec_status' \
+  --exclude='*.gem' \
+  --exclude='.DS_Store' \
+  "$AGENT_DIR/" "$CLONE_DIR/"
+
+# ---------- Commit + push ----------------------------------------------
+cd "$CLONE_DIR"
+git add -A
+if git diff --cached --quiet; then
+  echo "==> Working tree matches origin — nothing new to commit."
+else
+  COMMIT_MSG="Sync from ez_logs monorepo @ $(git -C "$AGENT_DIR" rev-parse --short HEAD)"
+  git commit -m "$COMMIT_MSG"
+fi
+
+# Are we ahead of origin? (covers commit-now, push-later case across runs.)
+LOCAL_HEAD="$(git rev-parse HEAD)"
+REMOTE_HEAD="$(git rev-parse "origin/$PUBLIC_BRANCH" 2>/dev/null || echo "")"
+if [ "$LOCAL_HEAD" = "$REMOTE_HEAD" ]; then
+  echo "==> Already in sync with origin/$PUBLIC_BRANCH. Nothing to push."
+  exit 0
+fi
+
+if $DRY_RUN; then
+  echo "==> Dry run — skipping push. Diff staged in $CLONE_DIR."
+  exit 0
+fi
+
+echo "==> Pushing to $PUBLIC_REPO..."
+git push -u origin "$PUBLIC_BRANCH"
+echo "==> Done. https://github.com/dezsirazvan/ez_logs_agent"

data/sig/ez_logs_agent.rbs

@@ -0,0 +1,4 @@
+module EzLogsAgent
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end