e11y 0.2.0 → 1.1.0

data/lib/e11y/event/base.rb

@@ -81,22 +81,38 @@ module E11y
         # - Auto-calculated retention_until from retention_period
         #
         # @param payload [Hash] Event data matching the schema
+        # @yield Optional block — measured for duration; adds :duration_ms to payload
         # @return [Hash] Event hash (includes metadata)
         #
-        # @example
+        # @example Without block
         #   UserSignupEvent.track(user_id: 123, email: "user@example.com")
         #   # => { event_name: "UserSignupEvent", payload: {...}, severity: :info, adapters: [:logs], ... }
         #
+        # @example With block (duration measurement)
+        #   Events::OrderPaid.track(order_id: '123') { ExternalPaymentService.charge! }
+        #   # => payload includes duration_ms automatically
+        #
         # @raise [E11y::ValidationError] if payload doesn't match schema (when validation runs)
-        def track(**payload)
+        def track(**payload, &block)
           return unless E11y.config.enabled
 
+          # Block form: execute block, measure duration, capture return value
+          block_result = nil
+          if block
+            start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+            block_result = yield
+            payload = payload.merge(duration_ms: Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - start)
+          end
+
+          # Severity: payload override (e.g. exception → :error) or class default
+          resolved_severity = payload[:severity] || payload["severity"] || severity
+
           # Build event data hash for pipeline processing
           event_data = {
             event_class: self,
             event_name: event_name,
             payload: payload,
-            severity: severity,
+            severity: resolved_severity,
             version: version,
             adapters: adapters,
             timestamp: Time.now.utc,
@@ -109,8 +125,8 @@ module E11y
           # Routing middleware is the LAST middleware and it writes to adapters directly
           E11y.config.built_pipeline.call(event_data)
 
-          # Return event data for testing/debugging
-          event_data
+          # With block: return block's result (caller cares about it); without: return event_data
+          block ? block_result : event_data
         end
 
         # Build event hash
@@ -240,9 +256,7 @@ module E11y
         #   end
         def severity(value = nil)
           if value
-            unless SEVERITIES.include?(value)
-              raise ArgumentError, "Invalid severity: #{value}. Must be one of: #{SEVERITIES.join(', ')}"
-            end
+            raise ArgumentError, "Invalid severity: #{value}. Must be one of: #{SEVERITIES.join(', ')}" unless SEVERITIES.include?(value)
 
             @severity = value
           end
@@ -263,13 +277,15 @@ module E11y
         #   class OrderPaidEventV2 < E11y::Event::Base
         #     version 2
         #   end
+        VERSION_REGEX = /V(\d+)$/
+
         def version(value = nil)
           @version = value if value
-          # Return explicitly set version OR inherit from parent (if set) OR default to 1
           return @version if @version
-          return superclass.version if superclass != E11y::Event::Base && superclass.instance_variable_get(:@version)
 
-          1
+          # Auto-extract from class name (e.g. OrderPaidV2 → 2)
+          match = name&.match(VERSION_REGEX)
+          match ? match[1].to_i : 1
         end
 
         # Set or get retention period for this event
@@ -299,14 +315,15 @@ module E11y
           @retention_period = value if value
           # Return explicitly set retention_period OR inherit from parent (if set) OR config default OR final fallback
           return @retention_period if @retention_period
-          if superclass != E11y::Event::Base && superclass.instance_variable_get(:@retention_period)
-            return superclass.retention_period
-          end
+          return superclass.retention_period if superclass != E11y::Event::Base && superclass.instance_variable_get(:@retention_period)
 
           # Fallback to configuration or 30 days
           E11y.configuration&.default_retention_period || 30.days
         end
 
+        # Convenience alias — matches Quick Start documentation.
+        alias retention retention_period
+
         # Set or get adapters for this event
         #
         # Adapters are referenced by NAME (e.g., :logs, :errors_tracker).
@@ -331,16 +348,42 @@ module E11y
           return @adapters if @adapters
           return superclass.adapters if superclass != E11y::Event::Base && superclass.instance_variable_get(:@adapters)
 
+          # No explicit adapters: inherit from parent or resolve from severity
+          # (audit events and regular events both use severity-based mapping)
           resolved_adapters
         end
 
-        # Get event name (normalized)
+        # Get or set event name (normalized)
         #
-        # @return [String] Event name without version suffix
+        # When called with a value, stores it and auto-registers the class in `E11y::Registry`.
+        # When called without a value, derives the name from the class name (stripping version suffix).
         #
-        # @example
+        # @param value [String, Symbol, nil] Explicit event name to set, or nil to read
+        # @return [String] Event name
+        #
+        # @example Explicit name
+        #   class OrderPaidEvent < E11y::Event::Base
+        #     event_name "order.paid"
+        #   end
+        #
+        # @example Auto-derived name
         #   OrderPaidEventV2.event_name # => "OrderPaidEvent"
-        def event_name
+        def event_name(value = nil)
+          if value
+            @event_name = value.to_s
+            @event_name_explicit = true
+            # Auto-register in E11y::Registry when an explicit name is set.
+            # Guard with defined? so that loading order does not matter.
+            # NOTE: call register AFTER setting @event_name_explicit so that any
+            # re-entrant call to event_name (from Registry#register) returns the
+            # correct value instead of falling through to the auto-derive path.
+            E11y::Registry.register(self) if defined?(E11y::Registry)
+            return @event_name
+          end
+
+          # Return explicitly-set name unconditionally (works for anonymous classes too)
+          return @event_name if @event_name_explicit
+
           # Don't cache for anonymous classes (name returns nil)
           return @event_name if @event_name && name
 
@@ -365,7 +408,6 @@ module E11y
         #   class CriticalEvent < E11y::Event::Base
         #     sample_rate 1.0  # 100% sampling
         #   end
-        # rubocop:disable Metrics/CyclomaticComplexity
         def sample_rate(value = nil)
           if value
             unless value.is_a?(Numeric) && value >= 0.0 && value <= 1.0
@@ -377,13 +419,10 @@ module E11y
 
           # Return explicitly set sample_rate OR inherit from parent (if set) OR nil (use resolve_sample_rate)
           return @sample_rate if @sample_rate
-          if superclass != E11y::Event::Base && superclass.instance_variable_get(:@sample_rate)
-            return superclass.sample_rate
-          end
+          return superclass.sample_rate if superclass != E11y::Event::Base && superclass.instance_variable_get(:@sample_rate)
 
           nil
         end
-        # rubocop:enable Metrics/CyclomaticComplexity
 
         # Configure value-based sampling (FEAT-4849)
         #
@@ -460,9 +499,7 @@ module E11y
 
           # Return explicitly set config OR inherit from parent (if set) OR nil
           return @adaptive_sampling if @adaptive_sampling
-          if superclass != E11y::Event::Base && superclass.instance_variable_get(:@adaptive_sampling)
-            return superclass.adaptive_sampling
-          end
+          return superclass.adaptive_sampling if superclass != E11y::Event::Base && superclass.instance_variable_get(:@adaptive_sampling)
 
           nil
         end
@@ -476,12 +513,36 @@ module E11y
         def resolve_rate_limit
           case severity
           when :error, :fatal
-            nil # Unlimited - не теряем ошибки
+            nil # Unlimited - never drop errors
           else
             1000 # 1000 events/sec
           end
         end
 
+        # Set a per-event-class rate limit for the RateLimiting middleware.
+        #
+        # Overrides the global rate limit for events of this class.
+        # error/fatal events are always exempt (never rate-limited).
+        #
+        # @param count [Integer] Max events allowed per window
+        # @param window [Numeric, ActiveSupport::Duration] Time window in seconds (default: 1.0)
+        #
+        # @example Strict limit for login failures (brute-force protection)
+        #   class Events::UserLoginFailed < E11y::Event::Base
+        #     rate_limit 100, window: 60
+        #   end
+        def rate_limit(count, window: 1.0)
+          @rate_limit_count = count
+          @rate_limit_window = window.to_f
+        end
+
+        # Per-event rate limit configuration.
+        #
+        # @return [Hash] { count: Integer|nil, window: Float|nil }
+        def rate_limit_config
+          { count: @rate_limit_count, window: @rate_limit_window }
+        end
+
         private
 
         # Determine if validation should run for this event
@@ -581,21 +642,21 @@ module E11y
         #   end
         def contains_pii(value = nil)
           if value.nil?
-            # Getter
+            return superclass.contains_pii if !instance_variable_defined?(:@contains_pii) && superclass.respond_to?(:contains_pii)
+
             @contains_pii
           else
-            # Setter
             @contains_pii = value
           end
         end
 
-        # Determine the PII filtering tier for this event.
-        # @return [Symbol] :tier1, :tier2, or :tier3
-        def pii_tier
+        # PII filtering mode for this event.
+        # @return [Symbol] :no_pii, :rails_filters, or :explicit_pii
+        def pii_filtering_mode
           case contains_pii
-          when false then :tier1
-          when true then :tier3
-          else :tier2 # Default if not explicitly declared
+          when false then :no_pii
+          when true then :explicit_pii
+          else :rails_filters # Default if not explicitly declared
           end
         end
 
@@ -610,15 +671,22 @@ module E11y
         #     allows :user_id, :amount
         #   end
         def pii_filtering(&)
-          @pii_filtering_config ||= { fields: {} }
+          if @pii_filtering_config.nil?
+            parent_config = superclass.respond_to?(:pii_filtering_config) && superclass.pii_filtering_config
+            @pii_filtering_config = parent_config ? { fields: parent_config[:fields].dup } : { fields: {} }
+          end
           builder = PIIFilteringBuilder.new(@pii_filtering_config)
           builder.instance_eval(&)
         end
 
-        # Get PII filtering configuration
+        # Get PII filtering configuration (inherits from superclass if not defined)
         #
-        # @return [Hash] PII filtering config
-        attr_reader :pii_filtering_config
+        # @return [Hash, nil] PII filtering config
+        def pii_filtering_config
+          return @pii_filtering_config if instance_variable_defined?(:@pii_filtering_config) && @pii_filtering_config
+
+          superclass.pii_filtering_config if superclass.respond_to?(:pii_filtering_config)
+        end
 
         # PII Filtering DSL Builder
         #
@@ -666,6 +734,30 @@ module E11y
           def allows(*fields)
             fields.each { |field| @config[:fields][field] = { strategy: :allow } }
           end
+
+          # Per-field config with exclude_adapters (Tier 3 per-adapter filtering).
+          #
+          # @param field [Symbol] Field name
+          # @yield Block with strategy, exclude_adapters
+          # @example
+          #   field :email do
+          #     strategy :hash
+          #     exclude_adapters [:file_audit]  # Audit gets original (GDPR)
+          #   end
+          def field(field_name, &)
+            return unless block_given?
+
+            opts = { strategy: :allow }
+            dsl = Class.new do
+              attr_reader :opts
+
+              def initialize(opts) = @opts = opts
+              def strategy(val) = @opts.[]=(:strategy, val)
+              def exclude_adapters(adapters) = @opts.[]=(:exclude_adapters, Array(adapters).map(&:to_sym))
+            end.new(opts)
+            dsl.instance_eval(&)
+            @config[:fields][field_name] = opts
+          end
         end
 
         # === Audit Event DSL (ADR-006, UC-012) ===
@@ -705,6 +797,33 @@ module E11y
           @audit_event == true
         end
 
+        # === DLQ Filter DSL (ADR-013, UC-021) ===
+
+        # Declare whether this event should be saved to DLQ on failure.
+        #
+        # @param value [Boolean, nil] true = save, false = discard, nil = use severity + default
+        # @example
+        #   class Events::PaymentFailed < E11y::Event::Base
+        #     use_dlq true
+        #   end
+        #
+        #   class Events::DebugTrace < E11y::Event::Base
+        #     use_dlq false
+        #   end
+        def use_dlq(value = nil)
+          if value.nil?
+            return superclass.use_dlq if !instance_variable_defined?(:@use_dlq) && superclass.respond_to?(:use_dlq)
+
+            @use_dlq
+          else
+            @use_dlq = value
+          end
+        end
+
+        def use_dlq?
+          use_dlq == true
+        end
+
         # Configure cryptographic signing for audit event
         #
         # By default, all audit events are signed with HMAC-SHA256.
@@ -759,7 +878,7 @@ module E11y
           audit_event? && signing_enabled?
         end
 
-        # === Metrics DSL (ADR-002, UC-003) ===
+        # === Metrics DSL (ADR-002, UC-003 Event Metrics) ===
 
         # Define metrics for this event
         #
@@ -810,6 +929,23 @@ module E11y
           register_metrics_in_registry!
         end
 
+        # Single-call metric shorthand — equivalent to a one-metric `metrics` block.
+        #
+        # @param type [Symbol] :counter, :histogram, or :gauge
+        # @param name [Symbol] Metric name
+        # @param opts [Hash] Options: tags:, value: (histogram/gauge), buckets: (histogram)
+        #
+        # @example
+        #   metric :counter, name: :orders_total, tags: [:currency]
+        #   metric :histogram, name: :order_amount, value: :amount, tags: [:currency]
+        def metric(type, name:, **opts)
+          raise ArgumentError, "Unknown metric type: #{type}. Use :counter, :histogram, or :gauge" unless %i[counter histogram gauge].include?(type)
+
+          @metrics_config ||= []
+          @metrics_config << { type: type, name: name }.merge(opts).compact
+          register_metrics_in_registry!
+        end
+
         # Get metrics configuration
         #
         # @return [Array<Hash>] Metrics configuration
@@ -911,48 +1047,6 @@ module E11y
           end
         end
       end
-
-      # Builder for PII filtering DSL
-      class PIIFilteringBuilder
-        def initialize(config)
-          @config = config
-        end
-
-        # Mask fields (strategy: :mask)
-        def masks(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :mask }
-          end
-        end
-
-        # Hash fields (strategy: :hash)
-        def hashes(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :hash }
-          end
-        end
-
-        # Allow fields (strategy: :allow)
-        def allows(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :allow }
-          end
-        end
-
-        # Partial mask fields (strategy: :partial)
-        def partials(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :partial }
-          end
-        end
-
-        # Redact fields (strategy: :redact)
-        def redacts(*fields)
-          fields.each do |field|
-            @config[:fields][field] = { strategy: :redact }
-          end
-        end
-      end
     end
     # rubocop:enable Metrics/ClassLength
   end

data/lib/e11y/event/value_sampling_config.rb

@@ -69,7 +69,6 @@ module E11y
 
       private
 
-      # rubocop:disable Metrics/CyclomaticComplexity
       # Validation requires checking multiple comparison types and threshold types
       def validate_comparisons!
         raise ArgumentError, "At least one comparison required" if comparisons.empty?
@@ -79,12 +78,9 @@ module E11y
 
           raise ArgumentError, "in_range requires a Range" if type == :in_range && !threshold.is_a?(Range)
 
-          if NUMERIC_COMPARISON_TYPES.include?(type) && !threshold.is_a?(Numeric)
-            raise ArgumentError, "#{type} requires a Numeric threshold"
-          end
+          raise ArgumentError, "#{type} requires a Numeric threshold" if NUMERIC_COMPARISON_TYPES.include?(type) && !threshold.is_a?(Numeric)
         end
       end
-      # rubocop:enable Metrics/CyclomaticComplexity
     end
   end
 end

data/lib/e11y/events/rails/database/query.rb

@@ -16,10 +16,7 @@ module E11y
         # @example Custom override
         #   # config/initializers/e11y.rb
         #   E11y.configure do |config|
-        #     config.rails_instrumentation.event_class_for(
-        #       'sql.active_record',
-        #       MyApp::CustomDatabaseQuery
-        #     )
+        #     config.rails_instrumentation_custom_mappings['sql.active_record'] = MyApp::CustomDatabaseQuery
         #   end
         #
         # @see ADR-008 §4.3 (Built-in Event Classes)

data/lib/e11y/events/rails/job/failed.rb

@@ -12,6 +12,8 @@ module E11y
             optional(:job_class).maybe(:string)
             optional(:job_id).maybe(:string)
             optional(:queue).maybe(:string)
+            optional(:error_class).maybe(:string)
+            optional(:error_message).maybe(:string)
           end
 
           severity :error

data/lib/e11y/instruments/active_job.rb

@@ -29,13 +29,16 @@ module E11y
             # Store current trace as parent (job will create NEW trace)
             job.e11y_parent_trace_id = E11y::Current.trace_id if E11y::Current.trace_id
             job.e11y_parent_span_id = E11y::Current.span_id if E11y::Current.span_id
+            job.e11y_sampled = E11y::Current.sampled if E11y::Current.respond_to?(:sampled) && !E11y::Current.sampled.nil?
+            baggage = E11y::Tracing::Propagator.baggage_for_propagation_from_current
+            job.e11y_baggage = baggage if baggage.any?
           end
 
           # Set up job-scoped context around job execution (C17 Hybrid Tracing + C18 Non-Failing)
           around_perform do |job, block|
             # C18: Disable fail_on_error for jobs (observability should not block business logic)
-            original_fail_on_error = E11y.config.error_handling.fail_on_error
-            E11y.config.error_handling.fail_on_error = false
+            original_fail_on_error = E11y.config.error_handling_fail_on_error
+            E11y.config.error_handling_fail_on_error = false
 
             setup_job_context_active_job(job)
             setup_job_buffer_active_job
@@ -59,7 +62,7 @@ module E11y
             cleanup_job_context_active_job
 
             # Restore original setting
-            E11y.config.error_handling.fail_on_error = original_fail_on_error
+            E11y.config.error_handling_fail_on_error = original_fail_on_error
           end
         end
 
@@ -79,13 +82,28 @@ module E11y
           E11y::Current.span_id = span_id
           E11y::Current.parent_trace_id = parent_trace_id
           E11y::Current.request_id = job.job_id
+          E11y::Tracing::Propagator.hydrate_current_from_job_baggage!(job.e11y_baggage) if job.respond_to?(:e11y_baggage)
+
+          # Restore or compute sampling decision (ADR-005 §7)
+          if job.respond_to?(:e11y_sampled) && !job.e11y_sampled.nil?
+            E11y::Current.sampled = job.e11y_sampled
+          else
+            require "e11y/trace_context/sampler"
+            ctx = E11y::Current.to_context.merge(
+              job_class: job.class.name,
+              queue: job.queue_name
+            ).compact
+            E11y::Current.sampled = E11y::TraceContext::Sampler.should_sample?(ctx)
+          end
         end
 
         # Setup job-scoped buffer
         def setup_job_buffer_active_job
-          return unless E11y.config.request_buffer&.enabled
+          return unless E11y.config.ephemeral_buffer_enabled
 
-          E11y::Buffers::RequestScopedBuffer.initialize!
+          limit = E11y.config.ephemeral_buffer_job_buffer_limit ||
+                  E11y::Buffers::EphemeralBuffer::DEFAULT_BUFFER_LIMIT
+          E11y::Buffers::EphemeralBuffer.initialize!(buffer_limit: limit)
         rescue StandardError => e
           # C18: Don't fail job if buffer setup fails
           warn "[E11y] Failed to start job buffer: #{e.message}"
@@ -93,9 +111,9 @@ module E11y
 
         # Handle job error (C18: Non-Failing Event Tracking)
         def handle_job_error_active_job(_error)
-          return unless E11y.config.request_buffer&.enabled
+          return unless E11y.config.ephemeral_buffer_enabled
 
-          E11y::Buffers::RequestScopedBuffer.flush_on_error
+          E11y::Buffers::EphemeralBuffer.flush_on_error
         rescue StandardError => e
           # C18: Don't fail job if buffer flush fails
           warn "[E11y] Failed to flush job buffer on error: #{e.message}"
@@ -104,9 +122,9 @@ module E11y
         # Cleanup job-scoped context
         def cleanup_job_context_active_job
           # Flush buffer on success (not on error, already flushed in rescue)
-          if !$ERROR_INFO && E11y.config.request_buffer&.enabled
+          if !$ERROR_INFO && E11y.config.ephemeral_buffer_enabled
             begin
-              E11y::Buffers::RequestScopedBuffer.discard
+              E11y::Buffers::EphemeralBuffer.discard
             rescue StandardError => e
               # C18: Don't fail job if buffer flush fails
               warn "[E11y] Failed to flush job buffer: #{e.message}"
@@ -139,10 +157,9 @@ module E11y
         # @param start_time [Time] Job start time
         # @return [void]
         # @api private
-        # rubocop:disable Metrics/AbcSize
         # SLO tracking requires config check, duration calculation, method call, and error handling
         def track_job_slo_active_job(job, status, start_time)
-          return unless E11y.config.slo_tracking&.enabled
+          return unless E11y.config.slo_tracking_enabled
 
           duration_ms = ((Time.now - start_time) * 1000).round(2)
 
@@ -157,7 +174,6 @@ module E11y
           # C18: Don't fail if SLO tracking fails
           E11y.logger.warn("[E11y] SLO tracking error: #{e.message}", error: e.class.name)
         end
-        # rubocop:enable Metrics/AbcSize
       end
 
       # Custom attribute accessors for trace context (C17 Hybrid Tracing)
@@ -195,6 +211,22 @@ module E11y
         def e11y_span_id=(value)
           @e11y_span_id = value
         end
+
+        def e11y_sampled
+          @e11y_sampled
+        end
+
+        def e11y_sampled=(value)
+          @e11y_sampled = value
+        end
+
+        def e11y_baggage
+          @e11y_baggage
+        end
+
+        def e11y_baggage=(value)
+          @e11y_baggage = value
+        end
       end
     end
   end