e11y 0.2.0 → 1.1.0

data/lib/e11y/adapters/opentelemetry_collector.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+# OTLP HTTP adapter — requires Faraday
+begin
+  require "faraday"
+rescue LoadError
+  raise LoadError, <<~ERROR
+    Faraday not available!
+
+    To use E11y::Adapters::OpenTelemetryCollector, add to your Gemfile:
+
+      gem 'faraday'
+
+    Then run: bundle install
+  ERROR
+end
+
+require "e11y/opentelemetry/semantic_conventions"
+
+module E11y
+  module Adapters
+    # OpenTelemetry Collector adapter (ADR-007 §3, F1)
+    #
+    # Sends E11y events to OpenTelemetry Collector via OTLP HTTP.
+    # No OpenTelemetry SDK required — uses raw HTTP (Faraday).
+    #
+    # **Use case:** When you want to send logs to OTel Collector without
+    # loading the full OTel SDK (e.g. lightweight apps, or OTelLogs already
+    # handles in-process; this adapter sends to external Collector).
+    #
+    # @example Configuration
+    #   E11y.configure do |config|
+    #     config.adapters[:otel_collector] = E11y::Adapters::OpenTelemetryCollector.new(
+    #       endpoint: "http://localhost:4318",
+    #       service_name: "my-app"
+    #     )
+    #   end
+    #
+    # @see ADR-007 §3 OTel Collector Adapter
+    class OpenTelemetryCollector < Base
+      SEVERITY_MAPPING = {
+        debug: 5, info: 9, success: 9, warn: 13, error: 17, fatal: 21
+      }.freeze
+
+      def initialize(endpoint: nil, service_name: nil, headers: {}, timeout: 10, max_attributes: 50, compress: true, **)
+        super(**)
+        @endpoint = (endpoint || ENV["OTEL_EXPORTER_OTLP_ENDPOINT"] || "http://localhost:4318").chomp("/")
+        @service_name = service_name || E11y.config&.service_name || "e11y"
+        @headers = headers
+        @timeout = timeout
+        @max_attributes = max_attributes
+        @compress = compress
+        @connection = build_connection
+      end
+
+      def write(event_data)
+        payload = build_otlp_payload([event_data])
+        body = payload.to_json
+        body = compress_body(body) if @compress
+
+        response = @connection.post("/v1/logs") do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.headers["Content-Encoding"] = "gzip" if @compress
+          req.body = body
+        end
+        response.success?
+      rescue Faraday::Error => e
+        warn "[E11y::OpenTelemetryCollector] HTTP error: #{e.message}"
+        false
+      end
+
+      def healthy?
+        !@connection.nil?
+      end
+
+      def capabilities
+        { batching: false, compression: @compress, async: false, streaming: false }
+      end
+
+      private
+
+      def compress_body(body)
+        io = StringIO.new
+        gz = Zlib::GzipWriter.new(io)
+        gz.write(body)
+        gz.close
+        io.string
+      end
+
+      def build_connection
+        Faraday.new(url: @endpoint, request: { timeout: @timeout }) do |f|
+          @headers.each { |k, v| f.headers[k.to_s] = v }
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def build_otlp_payload(events)
+        log_records = events.map { |e| to_otel_log_record(e) }
+        {
+          resourceLogs: [{
+            resource: { attributes: resource_attributes },
+            scopeLogs: [{
+              scope: { name: "e11y", version: E11y::VERSION },
+              logRecords: log_records
+            }]
+          }]
+        }
+      end
+
+      def resource_attributes
+        [
+          { key: "service.name", value: { stringValue: @service_name } },
+          { key: "service.version", value: { stringValue: E11y::VERSION } },
+          { key: "deployment.environment", value: { stringValue: E11y.config&.environment || ENV["RAILS_ENV"] || "development" } },
+          { key: "host.name", value: { stringValue: hostname } },
+          { key: "process.pid", value: { intValue: Process.pid.to_s } }
+        ]
+      end
+
+      def hostname
+        require "socket"
+        Socket.gethostname
+      rescue StandardError
+        ENV["HOSTNAME"] || "unknown"
+      end
+
+      def to_otel_log_record(event)
+        ts = event[:timestamp] || Time.now.utc
+        ts_nano = (ts.to_f * 1_000_000_000).to_i
+        {
+          timeUnixNano: ts_nano.to_s,
+          observedTimeUnixNano: (Time.now.to_f * 1_000_000_000).to_i.to_s,
+          severityNumber: SEVERITY_MAPPING[event[:severity]] || 9,
+          severityText: (event[:severity] || :info).to_s.upcase,
+          body: { stringValue: event[:event_name] },
+          attributes: build_log_attributes(event),
+          traceId: encode_hex(event[:trace_id], 32),
+          spanId: encode_hex(event[:span_id], 16)
+        }.compact
+      end
+
+      def build_log_attributes(event)
+        attrs = []
+        attrs << { key: "event.name", value: { stringValue: event[:event_name] } }
+        attrs << { key: "event.version", value: { stringValue: event[:v].to_s } } if event[:v]
+        attrs << { key: "service.name", value: { stringValue: @service_name } }
+
+        payload = event[:payload] || {}
+        payload.each do |key, value|
+          break if attrs.size >= @max_attributes
+
+          otel_key = E11y::OpenTelemetry::SemanticConventions.map_key(event[:event_name], key)
+          attrs << encode_attr(otel_key, value)
+        end
+        attrs
+      end
+
+      def encode_attr(key, value)
+        case value
+        when String
+          { key: key.to_s, value: { stringValue: value } }
+        when Integer
+          { key: key.to_s, value: { intValue: value.to_s } }
+        when Float
+          { key: key.to_s, value: { doubleValue: value } }
+        when TrueClass, FalseClass
+          { key: key.to_s, value: { boolValue: value } }
+        else
+          { key: key.to_s, value: { stringValue: value.to_s } }
+        end
+      end
+
+      def encode_hex(str, expected_len)
+        return nil if str.to_s.empty?
+
+        s = str.to_s.gsub(/[^0-9a-fA-F]/, "")
+        return nil if s.length != expected_len
+
+        s.downcase
+      end
+    end
+  end
+end

data/lib/e11y/adapters/otel_logs.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require "e11y/opentelemetry/semantic_conventions"
+
 # Check if OpenTelemetry SDK is available
 begin
   require "opentelemetry/sdk"
   require "opentelemetry/logs"
+  require "opentelemetry-logs-sdk" # Provides OpenTelemetry::SDK::Logs::LoggerProvider
 rescue LoadError
   raise LoadError, <<~ERROR
     OpenTelemetry SDK not available!
@@ -11,7 +14,8 @@ rescue LoadError
     To use E11y::Adapters::OTelLogs, add to your Gemfile:
 
       gem 'opentelemetry-sdk'
-      gem 'opentelemetry-logs'
+      gem 'opentelemetry-logs-api'
+      gem 'opentelemetry-logs-sdk'
 
     Then run: bundle install
   ERROR
@@ -58,6 +62,12 @@ module E11y
     # @see ADR-007 for OpenTelemetry integration architecture
     # @see UC-008 for use cases
     class OTelLogs < Base
+      # Struct for test assertions (replaces OpenStruct per Style/OpenStructUse)
+      LogRecordStruct = Struct.new(
+        :timestamp, :observed_timestamp, :severity_number, :severity_text,
+        :body, :attributes, :trace_id, :span_id, :trace_flags
+      )
+
       # E11y severity → OTel severity_number mapping
       # See: https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber
       # Severity numbers: TRACE=1, DEBUG=5, INFO=9, WARN=13, ERROR=17, FATAL=21
@@ -70,7 +80,8 @@ module E11y
         fatal: 21  # FATAL
       }.freeze
 
-      # Default baggage allowlist (safe keys that don't contain PII)
+      # Default baggage allowlist kept for reference / backward compat.
+      # @deprecated Pass baggage_allowlist: :all (the new default) or an explicit Array.
       DEFAULT_BAGGAGE_ALLOWLIST = %i[
         trace_id
         span_id
@@ -82,24 +93,45 @@ module E11y
       # 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, **)
+      # @param baggage_allowlist [Array<Symbol>, :all] Keys to include in OTel attributes.
+      #   `:all` (default) passes every payload key — PII is already stripped upstream by
+      #   Middleware::PIIFilter before the adapter is called.
+      #   Pass an explicit Array for stricter filtering (backward compat).
+      # @param max_attributes [Integer] Max attributes per log (cardinality limit)
+      # @param cardinality_protection [Boolean] Use full 3-layer protection (C04). Default false for
+      #   logs (preserves user_id, order_id for debugging). Set true for cost-sensitive OTLP backends.
+      # @param endpoint [String, nil] OTLP endpoint (e.g. http://localhost:4318/v1/logs).
+      #   When set, logs are exported to OTel Collector. Default: in-process only.
+      def initialize(service_name: nil, baggage_allowlist: :all, max_attributes: 50, cardinality_protection: false, endpoint: nil, **)
         super(**)
         @service_name = service_name
         @baggage_allowlist = baggage_allowlist
         @max_attributes = max_attributes
+        @endpoint = endpoint
+        @use_cardinality_protection = cardinality_protection
+
+        if @use_cardinality_protection
+          require "e11y/metrics/cardinality_protection"
+          @cardinality_protection = E11y::Metrics::CardinalityProtection.new(
+            cardinality_limit: 1000,
+            overflow_strategy: :drop
+          )
+        else
+          @cardinality_protection = nil
+        end
 
         setup_logger_provider
       end
 
       # Write event to OTel Logs API
       #
+      # Uses Logger#on_emit (OTel SDK 0.4+) with keyword arguments.
+      #
       # @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)
+        params = build_log_record_params(event_data)
+        @logger.on_emit(**params)
         true
       rescue StandardError => e
         warn "[E11y::OTelLogs] Failed to write event: #{e.message}"
@@ -129,19 +161,73 @@ module E11y
 
       # Setup OTel Logger Provider
       def setup_logger_provider
-        @logger_provider = OpenTelemetry::SDK::Logs::LoggerProvider.new
+        resource = build_resource
+        @logger_provider = ::OpenTelemetry::SDK::Logs::LoggerProvider.new(resource: resource)
+
+        # Add OTLP exporter when endpoint configured (sends to OTel Collector)
+        if @endpoint
+          require "opentelemetry-exporter-otlp-logs"
+          exporter = ::OpenTelemetry::Exporter::OTLP::Logs::LogsExporter.new(endpoint: @endpoint)
+          processor = ::OpenTelemetry::SDK::Logs::Export::BatchLogRecordProcessor.new(exporter)
+          @logger_provider.add_log_record_processor(processor)
+        end
+
         @logger = @logger_provider.logger(
           name: "e11y",
           version: E11y::VERSION
         )
+      rescue LoadError => e
+        warn "[E11y::OTelLogs] OTLP export requested but opentelemetry-exporter-otlp-logs not available: #{e.message}"
+        resource = build_resource
+        @logger_provider ||= ::OpenTelemetry::SDK::Logs::LoggerProvider.new(resource: resource)
+        @logger = @logger_provider.logger(name: "e11y", version: E11y::VERSION)
+      end
+
+      # Build OTel Resource with full attributes (ADR-007 §7, F5).
+      #
+      # @return [::OpenTelemetry::SDK::Resources::Resource]
+      def build_resource
+        attrs = {}
+
+        # Service (required)
+        attrs["service.name"] = @service_name || E11y.config&.service_name || "e11y"
+        attrs["service.version"] = E11y::VERSION
+
+        # Deployment
+        attrs["deployment.environment"] = E11y.config&.environment || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+
+        # Host
+        attrs["host.name"] = hostname
+
+        # Process
+        attrs["process.pid"] = Process.pid
+
+        # Merge with OTel default (process.runtime, telemetry.sdk) when available
+        base = ::OpenTelemetry::SDK::Resources::Resource
+        resource = base.create(attrs)
+        resource = base.default.merge(resource) if base.respond_to?(:default)
+        resource
+      rescue StandardError
+        # Fallback: minimal resource
+        ::OpenTelemetry::SDK::Resources::Resource.create(
+          "service.name" => @service_name || "e11y",
+          "service.version" => E11y::VERSION
+        )
+      end
+
+      def hostname
+        require "socket"
+        Socket.gethostname
+      rescue StandardError
+        ENV["HOSTNAME"] || "unknown"
       end
 
-      # Build OTel log record from E11y event
+      # Build params for Logger#on_emit 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(
+      # @return [Hash] Keyword args for on_emit
+      def build_log_record_params(event_data)
+        {
           timestamp: event_data[:timestamp] || Time.now.utc,
           observed_timestamp: Time.now.utc,
           severity_number: map_severity(event_data[:severity]),
@@ -151,7 +237,16 @@ module E11y
           trace_id: event_data[:trace_id],
           span_id: event_data[:span_id],
           trace_flags: nil
-        )
+        }
+      end
+
+      # Build log record struct for testing (same data as build_log_record_params)
+      #
+      # @param event_data [Hash] E11y event payload
+      # @return [LogRecordStruct] Struct with attributes for test assertions
+      def build_log_record(event_data)
+        params = build_log_record_params(event_data)
+        LogRecordStruct.new(**params)
       end
 
       # Map E11y severity to OTel severity
@@ -165,39 +260,57 @@ module E11y
       # Build OTel attributes from E11y payload
       #
       # Applies:
+      # - Semantic conventions (ADR-007 §4, F4) — maps known keys to OTel semantic names
       # - Cardinality protection (C04 Resolution)
-      # - Baggage PII filtering (C08 Resolution)
+      # - Optional baggage allowlist filter (C08 Resolution — pass an Array to enable)
+      #
+      # By default (`baggage_allowlist: :all`) all payload keys are included.
+      # PII fields are stripped upstream by Middleware::PIIFilter before any adapter
+      # is called, so no additional filtering is needed at this layer.
       #
       # @param event_data [Hash] E11y event payload
       # @return [Hash] OTel attributes
       def build_attributes(event_data)
         attributes = {}
 
-        # Add event metadata
+        # Add event metadata (low cardinality)
         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
+        # C04: Optional cardinality protection (denylist + per-key limits). Off by default for logs.
+        if @cardinality_protection
+          payload_symbols = payload.transform_keys { |k| k.to_s.to_sym }
+          payload = @cardinality_protection.filter(payload_symbols, "otel_logs")
+        end
+
+        # Map payload to OTel semantic keys (F4)
+        payload.each do |key, value|
           next unless baggage_allowed?(key)
 
-          attributes["event.#{key}"] = value
+          otel_key = E11y::OpenTelemetry::SemanticConventions.map_key(
+            event_data[:event_name],
+            key
+          )
+          attributes[otel_key] = value
+          break if attributes.size >= @max_attributes
         end
 
         attributes
       end
 
-      # Check if key is allowed in baggage (C08 Resolution)
+      # Check if key is allowed in baggage.
+      #
+      # Returns true when allowlist is :all (default).
+      # Returns true only for listed keys when an explicit Array was configured.
       #
       # @param key [Symbol, String] Attribute key
-      # @return [Boolean] true if key is in allowlist
+      # @return [Boolean]
       def baggage_allowed?(key)
+        return true if @baggage_allowlist == :all
+
         @baggage_allowlist.include?(key.to_sym)
       end
     end

data/lib/e11y/adapters/sentry.rb

@@ -33,11 +33,8 @@ module E11y
     #     severity_threshold: :warn
     #   )
     #
-    # @example With Registry
-    #   E11y::Adapters::Registry.register(
-    #     :error_tracker,
-    #     E11y::Adapters::Sentry.new(dsn: ENV["SENTRY_DSN"])
-    #   )
+    # @example Configuration
+    #   config.adapters[:sentry] = E11y::Adapters::Sentry.new(dsn: ENV["SENTRY_DSN"])
     #
     # @see https://docs.sentry.io/platforms/ruby/
     # rubocop:disable Metrics/ClassLength
@@ -155,7 +152,7 @@ module E11y
       # Send error to Sentry
       #
       # @param event_data [Hash] Event data
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:disable Metrics/AbcSize
       # Sentry scope configuration requires multiple context enrichment steps
       def send_error_to_sentry(event_data)
         ::Sentry.with_scope do |scope|
@@ -187,7 +184,7 @@ module E11y
           end
         end
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize
 
       # Send breadcrumb to Sentry
       #

data/lib/e11y/adapters/stdout.rb

@@ -41,11 +41,12 @@ module E11y
       #
       # @param config [Hash] Configuration options
       # @option config [Boolean] :colorize (true) Enable colored output
-      # @option config [Boolean] :pretty_print (true) Enable pretty-printed JSON
+      # @option config [Boolean] :pretty_print (true) Enable pretty-printed JSON (when format: :json)
+      # @option config [Symbol] :format (:json) Output format: :json (JSON), :compact (single-line JSON), :rich (ADR-010 §3 structured)
       def initialize(config = {})
         @colorize = config.fetch(:colorize, true)
-        @pretty_print = config.fetch(:pretty_print, true)
-
+        @format = config.fetch(:format, :json)
+        @pretty_print = resolve_pretty_print(config)
         super
       end
 
@@ -82,15 +83,29 @@ module E11y
 
       private
 
+      # Resolve pretty_print from format or pretty_print keys
+      #
+      # @param config [Hash] Adapter config
+      # @return [Boolean]
+      def resolve_pretty_print(config)
+        return config[:pretty_print] if config.key?(:pretty_print)
+
+        case config[:format]
+        when :compact then false
+        when :pretty then true
+        else config.fetch(:pretty_print, true)
+        end
+      end
+
       # Format event for console output
       #
       # @param event_data [Hash] Event data
       # @return [String] Formatted output
       def format_event(event_data)
-        if @pretty_print
-          JSON.pretty_generate(event_data)
-        else
-          event_data.to_json
+        case @format
+        when :rich then format_event_rich(event_data)
+        when :compact then event_data.to_json
+        else @pretty_print ? JSON.pretty_generate(event_data) : event_data.to_json
         end
       end
 
@@ -103,6 +118,57 @@ module E11y
         color_code = SEVERITY_COLORS[severity] || ""
         "#{color_code}#{output}#{COLOR_RESET}"
       end
+
+      # Rich format: ADR-010 §3 — structured output with header, event name, payload, metadata
+      def format_event_rich(event_data)
+        lines = []
+        lines << format_header(event_data)
+        lines << format_event_name_line(event_data)
+        lines << format_payload_section(event_data[:payload]) if event_data[:payload]&.any?
+        lines << format_metadata_section(event_data) if event_data[:trace_id] || event_data[:span_id]
+        lines << ("─" * 80)
+        lines.join("\n")
+      end
+
+      def format_header(event_data)
+        ts = event_data[:timestamp]
+        ts = Time.parse(ts) if ts.is_a?(String)
+        time_str = ts&.strftime("%H:%M:%S.%L") || "??:??:??.???"
+        sev = event_data[:severity].to_s.upcase.ljust(8)
+        "#{time_str} #{sev}"
+      end
+
+      def format_event_name_line(event_data)
+        name = event_data[:event_name].to_s
+        "  → #{name}"
+      end
+
+      def format_payload_section(payload)
+        lines = ["  Payload:"]
+        payload.each do |k, v|
+          lines << "    #{k}: #{format_value_rich(v)}"
+        end
+        lines.join("\n")
+      end
+
+      def format_metadata_section(event_data)
+        meta = { trace_id: event_data[:trace_id], span_id: event_data[:span_id] }.compact
+        return "" if meta.empty?
+
+        meta.map { |k, v| "    #{k}: #{v}" }.unshift("  Metadata:").join("\n")
+      end
+
+      def format_value_rich(value)
+        case value
+        when String then "\"#{value.length > 50 ? "#{value[0...50]}..." : value}\""
+        when Array then "[#{value.size} items]"
+        when Hash then "{#{value.size} keys}"
+        else value.inspect
+        end
+      end
     end
+
+    # Alias for ADR-010 §3 (Console Output) — Console and Stdout are the same adapter
+    Console = Stdout
   end
 end