e11y 0.1.0

data/lib/e11y/adapters/loki.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+# Check if Faraday is available
+begin
+  require "faraday"
+  require "faraday/retry" # Retry middleware
+rescue LoadError
+  raise LoadError, <<~ERROR
+    Faraday not available!
+
+    To use E11y::Adapters::Loki, add to your Gemfile:
+
+      gem 'faraday'
+      gem 'faraday-retry'
+
+    Then run: bundle install
+  ERROR
+end
+
+require "json"
+require "zlib"
+require_relative "../metrics/cardinality_protection"
+
+module E11y
+  module Adapters
+    # Loki adapter for shipping logs to Grafana Loki.
+    #
+    # Features:
+    # - Automatic batching for efficiency
+    # - Optional gzip compression
+    # - Configurable labels
+    # - Optional cardinality protection for labels (C04 Resolution, disabled by default)
+    # - Multi-tenant support
+    # - Thread-safe buffer
+    #
+    # @example Basic usage
+    #   adapter = E11y::Adapters::Loki.new(
+    #     url: "http://loki:3100",
+    #     labels: { app: "my_app", env: "production" },
+    #     batch_size: 100,
+    #     batch_timeout: 5
+    #   )
+    #
+    # @example With Registry
+    #   E11y::Adapters::Registry.register(
+    #     :loki_logger,
+    #     E11y::Adapters::Loki.new(url: ENV["LOKI_URL"])
+    #   )
+    #
+    # @example With Cardinality Protection (C04 Resolution - Enterprise)
+    #   # Enable for high-traffic environments to prevent label explosion
+    #   adapter = E11y::Adapters::Loki.new(
+    #     url: "http://loki:3100",
+    #     labels: { app: "my_app", env: "production" },
+    #     enable_cardinality_protection: true,  # Disabled by default
+    #     max_label_cardinality: 100            # Max unique values per label
+    #   )
+    #   # Note: High-cardinality labels (user_id, order_id) will be filtered
+    #
+    # @see https://grafana.com/docs/loki/latest/api/#push-log-entries-to-loki
+    # @see ADR-009 §8 (C04 Resolution - Universal Cardinality Protection)
+    class Loki < Base
+      # Default batch size (events)
+      DEFAULT_BATCH_SIZE = 100
+
+      # Default batch timeout (seconds)
+      DEFAULT_BATCH_TIMEOUT = 5
+
+      # Loki push endpoint
+      PUSH_PATH = "/loki/api/v1/push"
+
+      attr_reader :url, :labels, :batch_size, :batch_timeout, :compress, :tenant_id
+
+      # Initialize Loki adapter
+      #
+      # @param config [Hash] Configuration options
+      # @option config [String] :url (required) Loki server URL (e.g., "http://loki:3100")
+      # @option config [Hash] :labels ({}) Static labels to attach to all logs
+      # @option config [Integer] :batch_size (100) Number of events to batch before sending
+      # @option config [Integer] :batch_timeout (5) Max seconds to wait before flushing batch
+      # @option config [Boolean] :compress (true) Enable gzip compression
+      # @option config [String] :tenant_id (nil) Loki tenant ID (X-Scope-OrgID header)
+      # @option config [Boolean] :enable_cardinality_protection (false) Enable cardinality protection for labels (C04)
+      # @option config [Integer] :max_label_cardinality (100) Max unique values per label when protection enabled
+      def initialize(config = {})
+        @url = config[:url]
+        @labels = config.fetch(:labels, {})
+        @batch_size = config.fetch(:batch_size, DEFAULT_BATCH_SIZE)
+        @batch_timeout = config.fetch(:batch_timeout, DEFAULT_BATCH_TIMEOUT)
+        @compress = config.fetch(:compress, true)
+        @tenant_id = config[:tenant_id]
+        @enable_cardinality_protection = config.fetch(:enable_cardinality_protection, false)
+        @max_label_cardinality = config.fetch(:max_label_cardinality, 100)
+
+        @buffer = []
+        @buffer_mutex = Mutex.new
+        @connection = nil
+        @last_flush = Time.now
+
+        # C04: Optional cardinality protection (disabled by default for logs)
+        if @enable_cardinality_protection
+          @cardinality_protection = E11y::Metrics::CardinalityProtection.new(
+            max_unique_values: @max_label_cardinality
+          )
+        end
+
+        super
+
+        build_connection!
+      end
+
+      # Write a single event to buffer
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Boolean] Success status
+      def write(event_data)
+        @buffer_mutex.synchronize do
+          @buffer << event_data
+
+          flush_if_needed!
+        end
+
+        true
+      rescue StandardError => e
+        warn "E11y Loki adapter error: #{e.message}"
+        false
+      end
+
+      # Write a batch of events to buffer
+      #
+      # @param events [Array<Hash>] Array of event payloads
+      # @return [Boolean] Success status
+      def write_batch(events)
+        @buffer_mutex.synchronize do
+          @buffer.concat(events)
+
+          flush_if_needed!
+        end
+
+        true
+      rescue StandardError => e
+        warn "E11y Loki adapter batch error: #{e.message}"
+        false
+      end
+
+      # Close adapter and flush remaining events
+      def close
+        @buffer_mutex.synchronize do
+          flush_buffer! unless @buffer.empty?
+        end
+      end
+
+      # Check if adapter is healthy
+      #
+      # @return [Boolean] True if connection is established
+      def healthy?
+        @connection&.respond_to?(:get)
+      end
+
+      # Adapter capabilities
+      #
+      # @return [Hash] Capability flags
+      def capabilities
+        super.merge(
+          batching: true,
+          compression: @compress,
+          async: true,
+          streaming: false
+        )
+      end
+
+      private
+
+      # Validate configuration
+      def validate_config!
+        raise ArgumentError, "Loki adapter requires :url" unless @url
+        raise ArgumentError, "batch_size must be positive" if @batch_size <= 0
+        raise ArgumentError, "batch_timeout must be positive" if @batch_timeout <= 0
+      end
+
+      # Build Faraday connection with retry middleware
+      #
+      # Uses Faraday's built-in retry middleware for exponential backoff
+      # on transient network errors and 5xx responses.
+      #
+      # Note: Connection pooling is handled at HTTP client level (Net::HTTP persistent).
+      # Faraday reuses persistent connections by default. For advanced pooling,
+      # configure Faraday adapter (e.g., :net_http_persistent, :typhoeus).
+      #
+      # @see ADR-004 Section 7.1 (Retry Policy via gem-level middleware)
+      # @see ADR-004 Section 6.1 (Connection pooling via HTTP client)
+      def build_connection!
+        @connection = Faraday.new(url: @url) do |f|
+          # Retry middleware (exponential backoff: 1s, 2s, 4s)
+          f.request :retry,
+                    max: 3,
+                    interval: 1.0,
+                    backoff_factor: 2,
+                    interval_randomness: 0.2, # ±20% jitter
+                    retry_statuses: [429, 500, 502, 503, 504],
+                    methods: [:post],
+                    exceptions: [
+                      Faraday::TimeoutError,
+                      Faraday::ConnectionFailed,
+                      Errno::ECONNREFUSED,
+                      Errno::ETIMEDOUT
+                    ]
+
+          f.request :json
+          f.response :raise_error
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # Check if buffer should be flushed
+      def flush_if_needed!
+        should_flush = @buffer.size >= @batch_size ||
+                       (Time.now - @last_flush) >= @batch_timeout
+
+        flush_buffer! if should_flush
+      end
+
+      # Flush buffer to Loki
+      def flush_buffer!
+        return if @buffer.empty?
+
+        events = @buffer.dup
+        @buffer.clear
+        @last_flush = Time.now
+
+        # Release mutex before I/O
+        @buffer_mutex.unlock
+        begin
+          send_to_loki(events)
+        ensure
+          @buffer_mutex.lock
+        end
+      end
+
+      # Send events to Loki
+      #
+      # @param events [Array<Hash>] Events to send
+      def send_to_loki(events)
+        payload = format_loki_payload(events)
+        body = JSON.generate(payload)
+
+        body = compress_body(body) if @compress
+
+        headers = build_headers
+
+        @connection.post(PUSH_PATH, body, headers)
+      rescue Faraday::Error => e
+        warn "E11y Loki adapter HTTP error: #{e.message}"
+        false
+      end
+
+      # Format events as Loki payload
+      #
+      # @param events [Array<Hash>] Events to format
+      # @return [Hash] Loki push API payload
+      def format_loki_payload(events)
+        # Group events by labels
+        streams = events.group_by { |e| extract_labels(e) }.map do |labels, group_events|
+          {
+            stream: labels,
+            values: group_events.map { |e| format_loki_entry(e) }
+          }
+        end
+
+        { streams: streams }
+      end
+
+      # Extract labels from event
+      #
+      # @param event_data [Hash] Event data
+      # @return [Hash] Labels for Loki stream
+      def extract_labels(event_data)
+        event_labels = {
+          event_name: event_data[:event_name].to_s,
+          severity: event_data[:severity].to_s
+        }
+
+        # Merge static and event labels
+        all_labels = @labels.merge(event_labels)
+
+        # C04: Apply cardinality protection if enabled (enterprise use case)
+        # Disabled by default - Loki is a log system, labels are for stream filtering only
+        if @enable_cardinality_protection && @cardinality_protection
+          all_labels = @cardinality_protection.filter(all_labels, "loki.stream")
+        end
+
+        all_labels.transform_keys(&:to_s)
+      end
+
+      # Format single event as Loki entry
+      #
+      # @param event_data [Hash] Event data
+      # @return [Array] [timestamp_ns, line]
+      def format_loki_entry(event_data)
+        timestamp_ns = (event_data[:timestamp] || Time.now).to_f * 1_000_000_000
+        line = event_data.to_json
+
+        [timestamp_ns.to_i.to_s, line]
+      end
+
+      # Compress body with gzip
+      #
+      # @param body [String] Body to compress
+      # @return [String] Compressed body
+      def compress_body(body)
+        io = StringIO.new
+        gz = Zlib::GzipWriter.new(io)
+        gz.write(body)
+        gz.close
+        io.string
+      end
+
+      # Build HTTP headers
+      #
+      # @return [Hash] Headers for Loki request
+      def build_headers
+        headers = {
+          "Content-Type" => "application/json"
+        }
+
+        headers["Content-Encoding"] = "gzip" if @compress
+        headers["X-Scope-OrgID"] = @tenant_id if @tenant_id
+
+        headers
+      end
+    end
+  end
+end

data/lib/e11y/adapters/otel_logs.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+# Check if OpenTelemetry SDK is available
+begin
+  require "opentelemetry/sdk"
+  require "opentelemetry/logs"
+rescue LoadError
+  raise LoadError, <<~ERROR
+    OpenTelemetry SDK not available!
+
+    To use E11y::Adapters::OTelLogs, add to your Gemfile:
+
+      gem 'opentelemetry-sdk'
+      gem 'opentelemetry-logs'
+
+    Then run: bundle install
+  ERROR
+end
+
+module E11y
+  module Adapters
+    # OpenTelemetry Logs Adapter (ADR-007, UC-008)
+    #
+    # Sends E11y events to OpenTelemetry Logs API.
+    # Events are converted to OTel log records with proper severity mapping.
+    #
+    # **Features:**
+    # - Severity mapping (E11y → OTel)
+    # - Attributes mapping (E11y payload → OTel attributes)
+    # - Baggage PII protection (C08 Resolution)
+    # - Cardinality protection for attributes (C04 Resolution)
+    # - Optional dependency (requires opentelemetry-sdk gem)
+    #
+    # **ADR References:**
+    # - ADR-007 §4 (OpenTelemetry Integration)
+    # - ADR-006 §5 (Baggage PII Protection - C08 Resolution)
+    # - ADR-009 §8 (Cardinality Protection - C04 Resolution)
+    #
+    # **Use Case:** UC-008 (OpenTelemetry Integration)
+    #
+    # @example Configuration
+    #   # Gemfile
+    #   gem 'opentelemetry-sdk'
+    #   gem 'opentelemetry-logs'
+    #
+    #   # config/initializers/e11y.rb
+    #   E11y.configure do |config|
+    #     config.adapters[:otel_logs] = E11y::Adapters::OTelLogs.new(
+    #       service_name: 'my-app',
+    #       baggage_allowlist: [:trace_id, :span_id, :user_id]
+    #     )
+    #   end
+    #
+    # @example Baggage PII Protection (C08)
+    #   # Only allowlisted keys are sent to baggage
+    #   # PII keys (email, phone, etc.) are automatically dropped
+    #
+    # @see ADR-007 for OpenTelemetry integration architecture
+    # @see UC-008 for use cases
+    class OTelLogs < Base
+      # E11y severity → OTel severity mapping
+      SEVERITY_MAPPING = {
+        debug: OpenTelemetry::SDK::Logs::Severity::DEBUG,
+        info: OpenTelemetry::SDK::Logs::Severity::INFO,
+        success: OpenTelemetry::SDK::Logs::Severity::INFO, # OTel has no "success"
+        warn: OpenTelemetry::SDK::Logs::Severity::WARN,
+        error: OpenTelemetry::SDK::Logs::Severity::ERROR,
+        fatal: OpenTelemetry::SDK::Logs::Severity::FATAL
+      }.freeze
+
+      # Default baggage allowlist (safe keys that don't contain PII)
+      DEFAULT_BAGGAGE_ALLOWLIST = %i[
+        trace_id
+        span_id
+        request_id
+        environment
+        service_name
+      ].freeze
+
+      # Initialize OTel Logs adapter
+      #
+      # @param service_name [String] Service name for OTel (default: from config)
+      # @param baggage_allowlist [Array<Symbol>] Allowlist of safe baggage keys
+      # @param max_attributes [Integer] Max attributes per log (cardinality protection)
+      def initialize(service_name: nil, baggage_allowlist: DEFAULT_BAGGAGE_ALLOWLIST, max_attributes: 50, **)
+        super(**)
+        @service_name = service_name
+        @baggage_allowlist = baggage_allowlist
+        @max_attributes = max_attributes
+
+        setup_logger_provider
+      end
+
+      # Write event to OTel Logs API
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Boolean] true on success
+      def write(event_data)
+        log_record = build_log_record(event_data)
+        @logger.emit_log_record(log_record)
+        true
+      rescue StandardError => e
+        warn "[E11y::OTelLogs] Failed to write event: #{e.message}"
+        false
+      end
+
+      # Check if adapter is healthy
+      #
+      # @return [Boolean] true if OTel SDK available and configured
+      def healthy?
+        @logger_provider && @logger
+      end
+
+      # Adapter capabilities
+      #
+      # @return [Hash] Capabilities hash
+      def capabilities
+        {
+          batching: false, # OTel SDK handles batching internally
+          compression: false,
+          async: true, # OTel SDK is async by default
+          streaming: false
+        }
+      end
+
+      private
+
+      # Setup OTel Logger Provider
+      def setup_logger_provider
+        @logger_provider = OpenTelemetry::SDK::Logs::LoggerProvider.new
+        @logger = @logger_provider.logger(
+          name: "e11y",
+          version: E11y::VERSION
+        )
+      end
+
+      # Build OTel log record from E11y event
+      #
+      # @param event_data [Hash] E11y event payload
+      # @return [OpenTelemetry::SDK::Logs::LogRecord] OTel log record
+      def build_log_record(event_data)
+        OpenTelemetry::SDK::Logs::LogRecord.new(
+          timestamp: event_data[:timestamp] || Time.now.utc,
+          observed_timestamp: Time.now.utc,
+          severity_number: map_severity(event_data[:severity]),
+          severity_text: event_data[:severity].to_s.upcase,
+          body: event_data[:event_name],
+          attributes: build_attributes(event_data),
+          trace_id: event_data[:trace_id],
+          span_id: event_data[:span_id],
+          trace_flags: nil
+        )
+      end
+
+      # Map E11y severity to OTel severity
+      #
+      # @param severity [Symbol] E11y severity (:debug, :info, etc.)
+      # @return [Integer] OTel severity number
+      def map_severity(severity)
+        SEVERITY_MAPPING[severity] || OpenTelemetry::SDK::Logs::Severity::INFO
+      end
+
+      # Build OTel attributes from E11y payload
+      #
+      # Applies:
+      # - Cardinality protection (C04 Resolution)
+      # - Baggage PII filtering (C08 Resolution)
+      #
+      # @param event_data [Hash] E11y event payload
+      # @return [Hash] OTel attributes
+      def build_attributes(event_data)
+        attributes = {}
+
+        # Add event metadata
+        attributes["event.name"] = event_data[:event_name]
+        attributes["event.version"] = event_data[:v] if event_data[:v]
+        attributes["service.name"] = @service_name if @service_name
+
+        # Add payload (with cardinality protection)
+        payload = event_data[:payload] || {}
+        payload.each do |key, value|
+          # C04: Cardinality protection - limit attributes
+          break if attributes.size >= @max_attributes
+
+          # C08: Baggage PII protection - only allowlisted keys
+          next unless baggage_allowed?(key)
+
+          attributes["event.#{key}"] = value
+        end
+
+        attributes
+      end
+
+      # Check if key is allowed in baggage (C08 Resolution)
+      #
+      # @param key [Symbol, String] Attribute key
+      # @return [Boolean] true if key is in allowlist
+      def baggage_allowed?(key)
+        @baggage_allowlist.include?(key.to_sym)
+      end
+    end
+  end
+end

data/lib/e11y/adapters/registry.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module E11y
+  module Adapters
+    # Adapter Registry - Global registry for adapter instances
+    #
+    # Provides thread-safe registration and resolution of adapters.
+    # Adapters are registered once during configuration and reused
+    # throughout application lifetime.
+    #
+    # **Features:**
+    # - Thread-safe registration
+    # - Adapter validation
+    # - Resolution by name
+    # - Cleanup on exit
+    #
+    # @example Registration
+    #   E11y::Adapters::Registry.register :stdout, E11y::Adapters::Stdout.new
+    #   E11y::Adapters::Registry.register :loki, E11y::Adapters::Loki.new(url: "...")
+    #
+    # @example Resolution
+    #   adapter = E11y::Adapters::Registry.resolve(:stdout)
+    #   adapter.write(event_data)
+    #
+    # @see ADR-004 §5 (Adapter Registry)
+    class Registry
+      # Registry error
+      class Error < E11y::Error; end
+
+      # Adapter not found error
+      class AdapterNotFoundError < Error; end
+
+      class << self
+        # Register adapter instance
+        #
+        # @param name [Symbol] Adapter name (e.g., :stdout, :loki)
+        # @param adapter_instance [Adapters::Base] Adapter instance
+        # @raise [ArgumentError] if adapter does not respond to required methods
+        #
+        # @example
+        #   Registry.register :stdout, E11y::Adapters::Stdout.new
+        def register(name, adapter_instance)
+          validate_adapter!(adapter_instance)
+
+          adapters[name] = adapter_instance
+
+          # Register cleanup hook
+          at_exit { adapter_instance.close }
+        end
+
+        # Resolve adapter by name
+        #
+        # @param name [Symbol] Adapter name
+        # @return [Adapters::Base] Adapter instance
+        # @raise [AdapterNotFoundError] if adapter not found
+        #
+        # @example
+        #   adapter = Registry.resolve(:stdout)
+        def resolve(name)
+          adapters.fetch(name) do
+            raise AdapterNotFoundError, "Adapter not found: #{name}. Registered: #{names.join(', ')}"
+          end
+        end
+
+        # Resolve multiple adapters by names
+        #
+        # @param names [Array<Symbol>] Adapter names
+        # @return [Array<Adapters::Base>] Adapter instances
+        # @raise [AdapterNotFoundError] if any adapter not found
+        #
+        # @example
+        #   adapters = Registry.resolve_all([:stdout, :loki])
+        def resolve_all(names)
+          names.map { |name| resolve(name) }
+        end
+
+        # Get all registered adapters
+        #
+        # @return [Array<Adapters::Base>] All adapter instances
+        def all
+          adapters.values
+        end
+
+        # Get all registered adapter names
+        #
+        # @return [Array<Symbol>] Adapter names
+        def names
+          adapters.keys
+        end
+
+        # Check if adapter is registered
+        #
+        # @param name [Symbol] Adapter name
+        # @return [Boolean] true if registered
+        #
+        # @example
+        #   Registry.registered?(:stdout)  #=> true
+        def registered?(name)
+          adapters.key?(name)
+        end
+
+        # Clear all registered adapters
+        #
+        # Calls close() on all adapters and clears registry.
+        # Useful for testing.
+        #
+        # @return [void]
+        #
+        # @example
+        #   Registry.clear!
+        def clear!
+          adapters.each_value(&:close)
+          adapters.clear
+        end
+
+        private
+
+        # Registry storage (thread-safe Hash)
+        #
+        # @return [Hash<Symbol, Adapters::Base>]
+        def adapters
+          @adapters ||= {}
+        end
+
+        # Validate adapter implements required interface
+        #
+        # @param adapter [Object] Adapter instance
+        # @raise [ArgumentError] if adapter invalid
+        def validate_adapter!(adapter)
+          raise ArgumentError, "Adapter must respond to #write" unless adapter.respond_to?(:write)
+
+          raise ArgumentError, "Adapter must respond to #write_batch" unless adapter.respond_to?(:write_batch)
+
+          return if adapter.respond_to?(:healthy?)
+
+          raise ArgumentError, "Adapter must respond to #healthy?"
+        end
+      end
+    end
+  end
+end