e11y 0.2.0 → 1.0.0

data/lib/e11y/adapters/loki.rb

@@ -41,11 +41,8 @@ module E11y
     #     batch_timeout: 5
     #   )
     #
-    # @example With Registry
-    #   E11y::Adapters::Registry.register(
-    #     :loki_logger,
-    #     E11y::Adapters::Loki.new(url: ENV["LOKI_URL"])
-    #   )
+    # @example Configuration
+    #   config.adapters[:loki] = E11y::Adapters::Loki.new(url: ENV["LOKI_URL"])
     #
     # @example With Cardinality Protection (C04 Resolution - Enterprise)
     #   # Enable for high-traffic environments to prevent label explosion
@@ -82,8 +79,9 @@ module E11y
       # @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
+      # @option config [Boolean] :enable_cardinality_protection (true) Enable cardinality protection for labels (C04)
+      # @option config [Integer] :max_label_cardinality (1000) Max unique values per label when protection enabled.
+      #   Labels = event_name + severity only (payload stays in log line). 1000 covers ~1000 event types.
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       # Adapter initialization requires many instance variable assignments
       def initialize(config = {})
@@ -91,20 +89,22 @@ module E11y
         @labels = config.fetch(:labels, {})
         @batch_size = config.fetch(:batch_size, DEFAULT_BATCH_SIZE)
         @batch_timeout = config.fetch(:batch_timeout, DEFAULT_BATCH_TIMEOUT)
+        @timeout = config.fetch(:timeout, 5)
+        @health_check_timeout = [@timeout, 2].min
         @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)
+        @enable_cardinality_protection = config.fetch(:enable_cardinality_protection, true)
+        @max_label_cardinality = config.fetch(:max_label_cardinality, 1000)
 
         @buffer = []
         @buffer_mutex = Mutex.new
         @connection = nil
         @last_flush = Time.now
 
-        # C04: Optional cardinality protection (disabled by default for logs)
+        # C04: Cardinality protection for labels (enabled by default per ADR-009 §8)
         if @enable_cardinality_protection
           @cardinality_protection = E11y::Metrics::CardinalityProtection.new(
-            max_unique_values: @max_label_cardinality
+            cardinality_limit: @max_label_cardinality
           )
         end
 
@@ -155,11 +155,22 @@ module E11y
         end
       end
 
-      # Check if adapter is healthy
+      # Loki health check endpoint
+      READY_PATH = "/ready"
+
+      # Check if adapter is healthy (Loki server reachable)
+      #
+      # Performs actual HTTP GET to /ready. Returns false on connection failure,
+      # timeout, or non-2xx response.
       #
-      # @return [Boolean] True if connection is established
+      # @return [Boolean] True if Loki responds with 2xx
       def healthy?
-        @connection&.respond_to?(:get)
+        return false unless @connection
+
+        response = @connection.get(READY_PATH)
+        (200..299).cover?(response.status)
+      rescue Faraday::Error, Errno::ECONNREFUSED, Errno::ETIMEDOUT
+        false
       end
 
       # Adapter capabilities
@@ -194,7 +205,6 @@ module E11y
       #
       # @see ADR-004 Section 7.1 (Retry Policy via gem-level middleware)
       # @see ADR-004 Section 6.1 (Connection pooling via HTTP client)
-      # rubocop:disable Metrics/MethodLength
       # HTTP client configuration requires detailed retry and connection settings
       def build_connection!
         @connection = Faraday.new(url: @url) do |f|
@@ -218,7 +228,6 @@ module E11y
           f.adapter Faraday.default_adapter
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Check if buffer should be flushed
       def flush_if_needed!
@@ -280,22 +289,23 @@ module E11y
 
       # Extract labels from event
       #
+      # Uses normalized event_name (e.g., "Events::TestLoki" -> "test.loki") for consistent
+      # querying via LogQL. Matches Versioning middleware convention.
+      #
       # @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,
+          event_name: normalize_event_name_for_labels(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
+        # C04: Cardinality protection for labels only. Labels = event_name + severity (payload
+        # stays in log line). Filter by user_uuid via LogQL: | json | user_uuid="xxx"
+        all_labels = @cardinality_protection.filter(all_labels, "loki.stream") if @enable_cardinality_protection && @cardinality_protection
 
         all_labels.transform_keys(&:to_s)
       end
@@ -305,7 +315,17 @@ module E11y
       # @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
+        # Parse timestamp - can be Time object, ISO8601 string, or nil
+        timestamp = event_data[:timestamp]
+        timestamp = if timestamp.is_a?(String)
+                      Time.parse(timestamp)
+                    elsif timestamp.nil?
+                      Time.now
+                    else
+                      timestamp
+                    end
+
+        timestamp_ns = timestamp.to_f * 1_000_000_000
         line = event_data.to_json
 
         [timestamp_ns.to_i.to_s, line]
@@ -323,6 +343,21 @@ module E11y
         io.string
       end
 
+      # Normalize event name for Loki labels (matches Versioning middleware convention)
+      #
+      # @param name [String] Event name (e.g., "Events::TestLoki")
+      # @return [String] Normalized name (e.g., "test.loki")
+      def normalize_event_name_for_labels(name)
+        return name if name.nil? || name.empty?
+
+        n = name.sub(/^Events::/, "").sub(/V\d+$/, "")
+        n.gsub("::", ".")
+         .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+         .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+         .downcase
+         .tr("_", ".")
+      end
+
       # Build HTTP headers
       #
       # @return [Hash] Headers for Loki request

data/lib/e11y/adapters/null.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module E11y
+  module Adapters
+    # Null Adapter — silently discards all events.
+    #
+    # Designed for use in tests and development environments where you want
+    # to suppress all output while still being able to assert that events
+    # were tracked (via the `events` reader).
+    #
+    # @example In tests
+    #   RSpec.configure do |config|
+    #     config.before do
+    #       E11y.configure do |c|
+    #         c.adapters[:null] = E11y::Adapters::NullAdapter.new
+    #       end
+    #     end
+    #   end
+    #
+    # @example Asserting events
+    #   null_adapter = E11y::Adapters::NullAdapter.new
+    #   E11y.configure { |c| c.adapters[:null] = null_adapter }
+    #
+    #   Events::OrderPaid.track(order_id: "123", amount: 99.99)
+    #
+    #   expect(null_adapter.events.size).to eq(1)
+    #   expect(null_adapter.events.last[:event_name]).to eq("order.paid")
+    class Null < Base
+      attr_reader :events
+
+      # @param config [Hash] Options
+      # @option config [Boolean] :store_events (true) When false, truly discards (no retention).
+      #   Use store_events: false for memory profiling to measure pipeline-only allocations.
+      def initialize(config = {})
+        super
+        @store_events = config.fetch(:store_events, true)
+        @events = []
+        @mutex = Mutex.new
+      end
+
+      # Accept event. When store_events: true, stores for inspection. When false, truly discards.
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Boolean] always true
+      # rubocop:disable Naming/PredicateMethod -- implements Base adapter interface
+      def write(event_data)
+        @mutex.synchronize { @events << event_data.dup } if @store_events
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Accept batch. When store_events: true, stores for inspection. When false, truly discards.
+      #
+      # @param events [Array<Hash>] Event payloads
+      # @return [Boolean] always true
+      # rubocop:disable Naming/PredicateMethod -- implements Base adapter interface
+      def write_batch(events)
+        @mutex.synchronize { @events.concat(events.map(&:dup)) } if @store_events
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Clear all stored events (useful between test examples).
+      #
+      # @return [void]
+      def clear!
+        @mutex.synchronize { @events.clear }
+      end
+
+      def healthy?
+        true
+      end
+
+      def capabilities
+        { batching: true, compression: false, async: false, streaming: false, null: true }
+      end
+    end
+
+    # Convenience alias matching Quick Start documentation.
+    NullAdapter = Null
+  end
+end

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