e11y 0.2.0 → 1.0.0

data/lib/e11y/middleware/self_monitoring_emit.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "e11y/middleware/base"
+require "e11y/slo/config_loader"
+
+module E11y
+  module Middleware
+    # SelfMonitoringEmit middleware — emits e11y_events_tracked_total at pipeline end.
+    #
+    # When e11y_self_monitoring.enabled is true in slo.yml, increments the counter
+    # for each event that reaches the end of the pipeline (after EventSlo).
+    #
+    # **Middleware Zone:** `:post_processing` (last in pipeline)
+    #
+    # @example slo.yml
+    #   e11y_self_monitoring:
+    #     enabled: true
+    #     targets:
+    #       reliability: 0.999
+    #
+    # @see docs/plans/2026-03-13-slo-linters-self-monitoring-plan.md
+    class SelfMonitoringEmit < Base
+      middleware_zone :post_processing
+
+      # Process event and optionally emit self-monitoring metric.
+      #
+      # @param event_data [Hash, nil] Event payload (nil passes through)
+      # @return [Hash, nil] Unchanged event_data (passthrough)
+      def call(event_data)
+        if event_data && E11y::SLO::ConfigLoader.self_monitoring_enabled?
+          event_name = event_data[:event_name].to_s.presence || "unknown"
+          E11y::Metrics.increment(:e11y_events_tracked_total, result: "success", event_name: event_name)
+        end
+
+        @app&.call(event_data) || event_data
+      end
+    end
+  end
+end

data/lib/e11y/middleware/trace_context.rb

@@ -56,19 +56,19 @@ module E11y
       def call(event_data)
         enrich_trace_context(event_data)
         enrich_service_context(event_data)
-        increment_metric("e11y.middleware.trace_context.processed")
+        E11y::Metrics.increment("e11y.middleware.trace_context.processed")
         @app.call(event_data)
       end
 
       private
 
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/AbcSize
       # Add distributed tracing fields to event data
       # @param event_data [Hash] Event data to enrich
       # @return [void]
       def enrich_trace_context(event_data)
         event_data[:trace_id] ||= current_trace_id || generate_trace_id
-        event_data[:span_id] ||= generate_span_id
+        event_data[:span_id] ||= current_span_id || generate_span_id
         event_data[:parent_trace_id] ||= current_parent_trace_id if current_parent_trace_id
 
         # Format timestamp if it's a Time object
@@ -93,7 +93,7 @@ module E11y
 
         event_data[:audit_event] = event_class.audit_event?
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/AbcSize
 
       # Add service context fields to event data
       # @param event_data [Hash] Event data to enrich
@@ -103,15 +103,54 @@ module E11y
         event_data[:environment] ||= E11y.config.environment
       end
 
-      # Get current trace ID from E11y::Current or thread-local storage (request context).
+      # Get current trace ID from configured source (ADR-007 §8).
       #
-      # Priority: E11y::Current > Thread.current
+      # When config.tracing_source is :opentelemetry and OTel SDK has an active span,
+      # uses trace_id from OpenTelemetry::Trace.current_span.
+      # Otherwise: E11y::Current > Thread.current
       #
       # @return [String, nil] Current trace ID if set, nil otherwise
       def current_trace_id
+        if tracing_source_opentelemetry?
+          otel = otel_trace_context
+          return otel[:trace_id] if otel[:trace_id]
+        end
         E11y::Current.trace_id || Thread.current[:e11y_trace_id]
       end
 
+      # Get current span ID (for event correlation).
+      # When using OTel source and span exists, returns OTel span_id; otherwise nil (caller generates).
+      #
+      # @return [String, nil]
+      def current_span_id
+        return nil unless tracing_source_opentelemetry?
+
+        otel = otel_trace_context
+        otel[:span_id]
+      end
+
+      def tracing_source_opentelemetry?
+        E11y.config&.tracing_source == :opentelemetry
+      end
+
+      def otel_trace_context
+        return {} unless defined?(OpenTelemetry::Trace)
+
+        span = OpenTelemetry::Trace.current_span
+        ctx = span.context
+        return {} unless ctx.respond_to?(:valid?) && ctx.valid?
+
+        trace_id = ctx.respond_to?(:hex_trace_id) ? ctx.hex_trace_id : nil
+        span_id = ctx.respond_to?(:hex_span_id) ? ctx.hex_span_id : nil
+        return {} if trace_id.to_s.empty?
+
+        # Sync to E11y::Current so downstream uses same context
+        E11y::Current.trace_id = trace_id
+        E11y::Current.span_id = span_id
+
+        { trace_id: trace_id, span_id: span_id }
+      end
+
       # Get current parent trace ID from E11y::Current (background job context).
       #
       # Only set for background jobs that have a parent request trace.
@@ -151,10 +190,6 @@ module E11y
       #
       # @param metric_name [String] Metric name
       # @return [void]
-      def increment_metric(_metric_name)
-        # TODO: Integrate with Yabeda/Prometheus in Phase 2
-        # Yabeda.e11y.middleware_trace_context_processed.increment
-      end
     end
   end
 end

data/lib/e11y/middleware/track_latency.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # Measures Event.track() latency from pipeline entry to exit.
+    #
+    # Must be the FIRST middleware so it wraps the entire pipeline.
+    # Records duration for both success and dropped events.
+    #
+    # @see ADR-016 §3.1 (Performance Metrics)
+    # @example Add first in pipeline
+    #   config.pipeline.use E11y::Middleware::TrackLatency
+    #   config.pipeline.use E11y::Middleware::TraceContext
+    #   # ...
+    class TrackLatency < Base
+      middleware_zone :pre_processing
+
+      def call(event_data)
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = @app.call(event_data)
+        duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+
+        E11y::SelfMonitoring::PerformanceMonitor.track_latency(
+          duration_ms,
+          event_class: event_data[:event_name].to_s,
+          severity: event_data[:severity].to_s,
+          result: result.nil? ? :dropped : :success
+        )
+
+        result
+      end
+    end
+  end
+end

data/lib/e11y/middleware/validation.rb

@@ -56,7 +56,7 @@ module E11y
       # @option event_data [Hash] :payload The event payload (required)
       # @return [Hash, nil] Validated event data, or nil if dropped
       # @raise [E11y::ValidationError] if validation fails
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       def call(event_data)
         # Skip validation if no event_class or payload
         return @app.call(event_data) unless event_data[:event_class] && event_data[:payload]
@@ -69,7 +69,7 @@ module E11y
 
         # Skip validation if mode is :never
         if validation_mode == :never
-          increment_metric("e11y.middleware.validation.skipped")
+          E11y::Metrics.increment(:e11y_middleware_validation_total, result: "skipped")
           return @app.call(event_data)
         end
 
@@ -77,7 +77,7 @@ module E11y
         if validation_mode == :sampled
           sample_rate = event_class.respond_to?(:validation_sample_rate) ? event_class.validation_sample_rate : 0.01
           if rand >= sample_rate
-            increment_metric("e11y.middleware.validation.skipped")
+            E11y::Metrics.increment(:e11y_middleware_validation_total, result: "skipped")
             return @app.call(event_data)
           end
         end
@@ -87,7 +87,7 @@ module E11y
 
         # Skip validation if no schema defined (schema-less events)
         unless schema
-          increment_metric("e11y.middleware.validation.skipped")
+          E11y::Metrics.increment(:e11y_middleware_validation_total, result: "skipped")
           return @app.call(event_data)
         end
 
@@ -96,17 +96,17 @@ module E11y
 
         if result.success?
           # Validation passed
-          increment_metric("e11y.middleware.validation.passed")
+          E11y::Metrics.increment(:e11y_middleware_validation_total, result: "passed")
           @app.call(event_data)
         else
           # Validation failed - raise error with details
-          increment_metric("e11y.middleware.validation.failed")
+          E11y::Metrics.increment(:e11y_middleware_validation_total, result: "failed")
 
           error_message = format_validation_errors(event_class, result.errors)
           raise E11y::ValidationError, error_message
         end
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       private
 
@@ -122,15 +122,6 @@ module E11y
 
         "Validation failed for #{event_class.name}: #{error_details}"
       end
-
-      # Placeholder for metrics instrumentation.
-      #
-      # @param metric_name [String] Metric name
-      # @return [void]
-      def increment_metric(_metric_name)
-        # TODO: Integrate with Yabeda/Prometheus in Phase 2
-        # Yabeda.e11y.middleware_validation_passed.increment
-      end
     end
   end
 end

data/lib/e11y/middleware/versioning.rb

@@ -54,43 +54,47 @@ module E11y
     # @see ADR-012 for versioning architecture
     # @see UC-020 for use cases
     class Versioning < Base
-      # Version extraction regex (matches V2, V3, etc. at end of class name)
-      VERSION_REGEX = /V(\d+)$/
+      middleware_zone :pre_processing
+      VERSION_REGEX = E11y::Versioning::VersionExtractor::VERSION_REGEX
+
+      # Lazy cache: class name -> normalized event_name (per class, immutable)
+      NORMALIZED_CACHE = Concurrent::Map.new
 
       # Process event and add version field if needed
       #
       # @param event_data [Hash] Event payload
       # @return [Hash] Event data with version field (if > 1)
       def call(event_data)
-        # Extract version from event_name (class name)
-        version = extract_version(event_data[:event_name])
+        klass = event_data[:event_class]
+        class_name = klass&.name
 
-        # Add version field only if > 1 (ADR-012 §4.2)
+        version = event_data[:version].to_i
+        version = extract_version(class_name) if version <= 1
         event_data[:v] = version if version > 1
 
-        # Normalize event_name (remove version suffix for consistent queries)
-        event_data[:event_name] = normalize_event_name(event_data[:event_name])
+        # event_data[:event_name] set by Base; fallback to klass.event_name for minimal event_data (tests)
+        incoming = event_data[:event_name]
+        incoming = klass.event_name if incoming.nil? && klass.respond_to?(:event_name)
+        incoming = incoming.to_s
+        # Custom uses dot notation ("order.paid"); default from Base uses "::"
+        event_data[:event_name] = incoming != "" && !incoming.include?("::") ? incoming : normalized_for(klass)
 
-        event_data
+        @app&.call(event_data) || event_data
       end
 
       private
 
-      # Extract version from event class name
-      #
-      # @param class_name [String] Event class name (e.g., "Events::OrderPaidV2")
-      # @return [Integer] Version number (default: 1)
-      #
-      # @example
-      #   extract_version("Events::OrderPaid")   => 1
-      #   extract_version("Events::OrderPaidV2") => 2
-      #   extract_version("Events::OrderPaidV3") => 3
-      def extract_version(class_name)
-        return 1 unless class_name
+      def normalized_for(klass)
+        return unless klass
 
-        # Extract version from class name (e.g., "Events::OrderPaidV2" → 2)
-        match = class_name.match(VERSION_REGEX)
-        match ? match[1].to_i : 1
+        name = klass.name
+        return unless name
+
+        NORMALIZED_CACHE.fetch(name) { NORMALIZED_CACHE[name] = normalize_event_name(name) }
+      end
+
+      def extract_version(class_name)
+        E11y::Versioning::VersionExtractor.extract_version(class_name)
       end
 
       # Normalize event_name by removing version suffix

data/lib/e11y/opentelemetry/semantic_conventions.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module E11y
+  module OpenTelemetry
+    # Semantic conventions mapper for OTel attributes (ADR-007 §4, F4).
+    #
+    # Maps E11y payload keys to OpenTelemetry semantic convention attribute names.
+    # When event_name matches a convention type (http, database, etc.), known keys
+    # are mapped to semantic names (e.g. method → http.method).
+    #
+    # @see https://opentelemetry.io/docs/specs/semconv/
+    class SemanticConventions
+      # Key mappings by convention type
+      # https://opentelemetry.io/docs/specs/semconv/http/
+      # https://opentelemetry.io/docs/specs/semconv/database/
+      # https://opentelemetry.io/docs/specs/semconv/exceptions/
+      CONVENTIONS = {
+        http: {
+          "method" => "http.method",
+          "route" => "http.route",
+          "path" => "http.target",
+          "status_code" => "http.status_code",
+          "status" => "http.status_code",
+          "duration_ms" => "http.server.duration",
+          "request_size" => "http.request.body.size",
+          "response_size" => "http.response.body.size",
+          "user_agent" => "http.user_agent",
+          "client_ip" => "http.client_ip",
+          "scheme" => "http.scheme",
+          "host" => "http.host",
+          "server_name" => "http.server_name"
+        },
+        database: {
+          "query" => "db.statement",
+          "statement" => "db.statement",
+          "duration_ms" => "db.operation.duration",
+          "rows_affected" => "db.operation.rows_affected",
+          "connection_id" => "db.connection.id",
+          "database_name" => "db.name",
+          "table_name" => "db.sql.table",
+          "operation" => "db.operation"
+        },
+        rpc: {
+          "service" => "rpc.service",
+          "method" => "rpc.method",
+          "system" => "rpc.system",
+          "status_code" => "rpc.grpc.status_code"
+        },
+        messaging: {
+          "queue_name" => "messaging.destination.name",
+          "message_id" => "messaging.message.id",
+          "conversation_id" => "messaging.message.conversation_id",
+          "payload_size" => "messaging.message.payload_size_bytes",
+          "operation" => "messaging.operation"
+        },
+        exception: {
+          "error_type" => "exception.type",
+          "error_message" => "exception.message",
+          "error_class" => "exception.type",
+          "stacktrace" => "exception.stacktrace"
+        }
+      }.freeze
+
+      # Map payload keys to OTel semantic attribute names.
+      #
+      # @param event_name [String] Event name (used to detect convention type)
+      # @param payload [Hash] Event payload
+      # @return [Hash] Mapped payload with semantic keys where applicable
+      def self.map(event_name, payload)
+        convention_type = detect_convention_type(event_name)
+        return payload.transform_keys { |k| "event.#{k}" } unless convention_type
+
+        conventions = CONVENTIONS[convention_type]
+        payload.each_with_object({}) do |(key, value), mapped|
+          otel_key = conventions[key.to_s] || "event.#{key}"
+          mapped[otel_key] = value
+        end
+      end
+
+      # Map a single key to OTel semantic attribute name.
+      #
+      # @param event_name [String] Event name (used to detect convention type)
+      # @param key [String, Symbol] Payload key
+      # @return [String] OTel attribute key
+      def self.map_key(event_name, key)
+        convention_type = detect_convention_type(event_name)
+        return "event.#{key}" unless convention_type
+
+        conventions = CONVENTIONS[convention_type]
+        conventions[key.to_s] || "event.#{key}"
+      end
+
+      # Detect convention type from event name
+      #
+      # @param event_name [String]
+      # @return [Symbol, nil]
+      def self.detect_convention_type(event_name)
+        name = event_name.to_s
+        return :http if name.match?(/http|request|response/i)
+        return :database if name.match?(/database|query|sql|postgres|mysql/i)
+        return :rpc if name.match?(/rpc|grpc/i)
+        return :messaging if name.match?(/message|queue|kafka|rabbitmq|sidekiq|job/i)
+        return :exception if name.match?(/error|exception|failure/i)
+
+        nil
+      end
+    end
+  end
+end

data/lib/e11y/opentelemetry/span_creator.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "e11y/opentelemetry/semantic_conventions"
+
+module E11y
+  module OpenTelemetry
+    # Creates OpenTelemetry spans from E11y events (ADR-007 §6, F2).
+    #
+    # When enabled via config.opentelemetry_span_creation_patterns, creates
+    # OTel spans for matching events. Errors/fatal always create spans.
+    # Uses SemanticConventions for attribute mapping when applicable.
+    #
+    # @example Configuration
+    #   E11y.configure do |config|
+    #     config.opentelemetry_span_creation_patterns = ["order.*", "payment.*"]
+    #   end
+    #
+    # @see ADR-007 §6 Traces Signal Export
+    # @see E11y::OpenTelemetry::SemanticConventions
+    class SpanCreator
+      ATTR_EVENT_NAME = "event.name"
+      ATTR_SEVERITY = "event.severity"
+      ATTR_E11Y_TRACE_ID = "e11y.trace_id"
+      ATTR_E11Y_SPAN_ID = "e11y.span_id"
+
+      class << self
+        def create_span_from_event(event_data)
+          return unless defined?(::OpenTelemetry::Trace)
+          return unless should_create_span?(event_data)
+
+          tracer = ::OpenTelemetry.tracer_provider.tracer("e11y", E11y::VERSION)
+          parent_ctx = ::OpenTelemetry::Context.current
+          start_ts = time_to_nano(event_data[:timestamp] || Time.now)
+
+          span = tracer.start_span(
+            span_name(event_data),
+            with_parent: parent_ctx,
+            kind: span_kind(event_data),
+            start_timestamp: start_ts
+          )
+
+          set_attributes(span, event_data)
+          set_status(span, event_data)
+          record_exception(span, event_data) if event_data[:severity].in?(%i[error fatal])
+
+          end_ts = compute_end_timestamp(event_data)
+          span.finish(end_timestamp: end_ts)
+
+          span
+        end
+
+        private
+
+        def span_name(event_data)
+          event_data[:event_name].to_s.presence || "e11y.event"
+        end
+
+        def set_attributes(span, event_data)
+          span.set_attribute(ATTR_EVENT_NAME, event_data[:event_name].to_s)
+          span.set_attribute(ATTR_SEVERITY, event_data[:severity].to_s)
+          span.set_attribute(ATTR_E11Y_TRACE_ID, event_data[:trace_id].to_s) if event_data[:trace_id]
+          span.set_attribute(ATTR_E11Y_SPAN_ID, event_data[:span_id].to_s) if event_data[:span_id]
+
+          payload = event_data[:payload] || {}
+          return if payload.empty?
+
+          mapped = E11y::OpenTelemetry::SemanticConventions.map(event_data[:event_name].to_s, payload)
+          mapped.each do |key, value|
+            next if value.nil?
+
+            span.set_attribute(key.to_s, otel_value(value))
+          rescue ArgumentError, TypeError
+            span.set_attribute(key.to_s, value.to_s)
+          end
+        end
+
+        def otel_value(value)
+          case value
+          when TrueClass, FalseClass, Integer, Float, String then value
+          when Array then value.map(&:to_s)
+          else value.to_s # Symbol, NilClass, Hash, etc.
+          end
+        end
+
+        def set_status(span, event_data)
+          if event_data[:severity].in?(%i[error fatal])
+            msg = event_data.dig(:payload, :error_message) ||
+                  event_data.dig(:payload, "error_message") || "Error"
+            span.status = ::OpenTelemetry::Trace::Status.error(msg.to_s)
+          else
+            span.status = ::OpenTelemetry::Trace::Status.ok
+          end
+        end
+
+        def record_exception(span, event_data)
+          exc = event_data[:exception] || event_data.dig(:payload, :exception) || event_data.dig(:payload, "exception")
+          span.record_exception(exc) if exc.is_a?(Exception)
+        end
+
+        def compute_end_timestamp(event_data)
+          start = event_data[:timestamp] || Time.now
+          start_ns = time_to_nano(start)
+          if event_data[:duration_ms]
+            start_ns + (event_data[:duration_ms].to_f * 1_000_000).to_i
+          else
+            time_to_nano(Time.now)
+          end
+        end
+
+        def should_create_span?(event_data)
+          return true if event_data[:severity].in?(%i[error fatal])
+
+          patterns = E11y.config&.opentelemetry_span_creation_patterns || []
+          event_name = event_data[:event_name].to_s
+          return false if event_name.empty?
+
+          patterns.any? { |p| File.fnmatch(p.to_s, event_name) }
+        end
+
+        def span_kind(event_data)
+          kind = (event_data[:span_kind] || :internal).to_sym
+          case kind
+          when :server then ::OpenTelemetry::Trace::SpanKind::SERVER
+          when :client then ::OpenTelemetry::Trace::SpanKind::CLIENT
+          when :producer then ::OpenTelemetry::Trace::SpanKind::PRODUCER
+          when :consumer then ::OpenTelemetry::Trace::SpanKind::CONSUMER
+          else ::OpenTelemetry::Trace::SpanKind::INTERNAL
+          end
+        rescue StandardError
+          ::OpenTelemetry::Trace::SpanKind::INTERNAL
+        end
+
+        def time_to_nano(time)
+          return (Time.now.to_f * 1_000_000_000).to_i if time.nil?
+
+          time = Time.parse(time.to_s) if time.is_a?(String)
+          (time.to_f * 1_000_000_000).to_i
+        end
+      end
+    end
+  end
+end

data/lib/e11y/pii/patterns.rb

@@ -15,7 +15,7 @@ module E11y
       EMAIL = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/
 
       # Password-like field names
-      PASSWORD_FIELDS = /password|passwd|pwd|secret|token|api[_-]?key/i
+      PASSWORD_FIELDS = /\b(?:password|passwd|pwd|secret|token|api[_-]?key)\b/i
 
       # Social Security Number (US format: XXX-XX-XXXX)
       SSN = /\b\d{3}-\d{2}-\d{4}\b/
@@ -40,6 +40,17 @@ module E11y
         PHONE
       ].freeze
 
+      # Patterns applied to STRING VALUES only (excludes PASSWORD_FIELDS).
+      # PASSWORD_FIELDS matches field names (password, token, api_key), not values.
+      # Applying it to values corrupts legitimate strings like "process_token_renewal_completed".
+      VALUE_PATTERNS = [
+        EMAIL,
+        SSN,
+        CREDIT_CARD,
+        IPV4,
+        PHONE
+      ].freeze
+
       # Field name patterns that indicate PII
       # Used for field-level detection (case-insensitive)
       FIELD_PATTERNS = {

data/lib/e11y/pipeline/builder.rb

@@ -33,7 +33,7 @@ module E11y
     # @see ADR-015 §3.4 Middleware Zones & Modification Rules
     class Builder
       # Middleware entry: [middleware_class, args, options]
-      MiddlewareEntry = Struct.new(:middleware_class, :args, :options, keyword_init: true)
+      MiddlewareEntry = Struct.new(:middleware_class, :args, :options)
 
       # @return [Array<MiddlewareEntry>] Registered middlewares
       attr_reader :middlewares

data/lib/e11y/presets/audit_event.rb

@@ -38,11 +38,13 @@ module E11y
     module AuditEvent
       def self.included(base)
         base.class_eval do
-          # Audit events will use audit pipeline (Phase 4)
+          audit_event true
+          contains_pii false # Preserve all data for signing (Tier 1 = skip filtering)
+          use_dlq true # Audit events always saved to DLQ (compliance)
           # Severity is NOT set by preset - user decides based on event criticality
         end
 
-        # Extend class with audit-specific methods
+        # Extend class with audit-specific methods (resolve_sample_rate 1.0, resolve_rate_limit nil)
         base.extend(ClassMethods)
       end
 
@@ -59,6 +61,15 @@ module E11y
         def resolve_sample_rate
           1.0 # 100% - compliance requirement
         end
+
+        # Audit events use routing rules (UC-012), not severity-based adapters.
+        # Return [] when no explicit adapters; respect explicit adapters when set.
+        def adapters(*list)
+          @adapters = list.flatten if list.any?
+          return @adapters if @adapters
+
+          []
+        end
       end
     end
   end