e11y 0.2.0 → 1.0.0

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

data/lib/e11y/adapters/yabeda.rb

@@ -43,7 +43,7 @@ module E11y
     #   # Events automatically update metrics via middleware
     #
     # @see ADR-002 Metrics & Yabeda Integration
-    # @see UC-003 Pattern-Based Metrics
+    # @see UC-003 Event Metrics
     # rubocop:disable Metrics/ClassLength
     # Yabeda adapter contains metrics registration and update logic as cohesive unit
     class Yabeda < Base
@@ -67,6 +67,8 @@ module E11y
         return unless config.fetch(:auto_register, true)
 
         register_metrics_from_registry!
+        register_middleware_metrics!
+        register_self_monitoring_metrics!
 
         # Apply configuration in non-Rails environments (Rails does this automatically)
         # In tests, Yabeda.configure! should be called explicitly in before blocks
@@ -108,9 +110,10 @@ module E11y
 
       # Check if adapter is healthy
       #
-      # @return [Boolean] true if Yabeda is available and configured
+      # @return [Boolean] true if Yabeda is available, configured, and e11y group exists
       def healthy?
         return false unless defined?(::Yabeda)
+        return false unless ::Yabeda.respond_to?(:e11y)
 
         ::Yabeda.configured?
       rescue StandardError
@@ -151,8 +154,11 @@ module E11y
         # Register metric if not exists
         register_metric_if_needed(name, :counter, safe_labels.keys)
 
-        # Update Yabeda metric
-        ::Yabeda.e11y.send(name).increment(safe_labels, by: value)
+        # Update Yabeda metric (guard against nil when metric wasn't registered, e.g. after configure!)
+        metric = ::Yabeda.e11y.send(name)
+        return unless metric
+
+        metric.increment(safe_labels, by: value)
       rescue StandardError => e
         E11y.logger.warn("Failed to increment Yabeda metric #{name}: #{e.message}")
       end
@@ -173,8 +179,11 @@ module E11y
         # Register metric if not exists
         register_metric_if_needed(name, :histogram, safe_labels.keys, buckets: buckets)
 
-        # Update Yabeda metric
-        ::Yabeda.e11y.send(name).measure(safe_labels, value)
+        # Update Yabeda metric (guard against nil when metric wasn't registered)
+        metric = ::Yabeda.e11y.send(name)
+        return unless metric
+
+        metric.measure(safe_labels, value)
       rescue StandardError => e
         E11y.logger.warn("Failed to observe Yabeda histogram #{name}: #{e.message}")
       end
@@ -194,8 +203,11 @@ module E11y
         # Register metric if not exists
         register_metric_if_needed(name, :gauge, safe_labels.keys)
 
-        # Update Yabeda metric
-        ::Yabeda.e11y.send(name).set(safe_labels, value)
+        # Update Yabeda metric (guard against nil when metric wasn't registered)
+        metric = ::Yabeda.e11y.send(name)
+        return unless metric
+
+        metric.set(safe_labels, value)
       rescue StandardError => e
         E11y.logger.warn("Failed to set Yabeda gauge #{name}: #{e.message}")
       end
@@ -208,9 +220,7 @@ module E11y
         super
 
         # Validate cardinality_limit
-        if @config[:cardinality_limit] && !@config[:cardinality_limit].is_a?(Integer)
-          raise ArgumentError, "cardinality_limit must be an Integer"
-        end
+        raise ArgumentError, "cardinality_limit must be an Integer" if @config[:cardinality_limit] && !@config[:cardinality_limit].is_a?(Integer)
 
         # Validate forbidden_labels
         return unless @config[:forbidden_labels] && !@config[:forbidden_labels].is_a?(Array)
@@ -278,20 +288,112 @@ module E11y
         end
       end
 
+      # Pre-register middleware self-monitoring metrics.
+      #
+      # These metrics are used by TraceContext, Validation, and Routing middleware.
+      # Must be registered before Yabeda.configure! is called (e.g. in app initializers).
+      # Called during adapter initialization so they're available when events flow.
+      # Names use underscores (Prometheus requires /[a-zA-Z_:][a-zA-Z0-9_:]*/, no dots).
+      #
+      # @return [void]
+      def register_middleware_metrics!
+        return unless defined?(::Yabeda)
+
+        middleware_metrics = [
+          { name: :e11y_middleware_trace_context_processed, tags: [] },
+          { name: :e11y_middleware_validation_total, tags: [:result] },
+          { name: :e11y_middleware_routing_routed, tags: %i[adapters_count routing_type] }
+        ]
+
+        cardinality_metrics = [
+          { name: :e11y_cardinality_overflow_total, tags: %i[metric action strategy] },
+          { name: :e11y_cardinality_current, type: :gauge, tags: [:metric] }
+        ]
+
+        (middleware_metrics + cardinality_metrics).each do |m|
+          type = m[:type] || :counter
+          register_metric_if_needed(m[:name], type, m[:tags])
+        end
+      rescue StandardError => e
+        E11y.logger.debug("Could not register middleware metrics: #{e.message}")
+      end
+
+      # Pre-register self-monitoring metrics (request buffer, retry, circuit breaker, DLQ, etc.).
+      # Must be registered before Yabeda.configure! so they exist when reliability layer runs.
+      #
+      # @return [void] # -- metric list is inherently long
+      def register_self_monitoring_metrics!
+        return unless defined?(::Yabeda)
+
+        metrics = [
+          # Request buffer (consolidated)
+          { name: :e11y_ephemeral_buffer_total, tags: [:event] },
+          # Retry handler
+          { name: :e11y_retry_success, tags: %i[adapter attempts] },
+          { name: :e11y_retry_recovered, tags: %i[adapter attempts] },
+          { name: :e11y_retry_permanent_failure, tags: %i[adapter error attempt] },
+          { name: :e11y_retry_exhausted, tags: %i[adapter error attempts] },
+          { name: :e11y_retry_attempt, tags: %i[adapter error attempt] },
+          # Circuit breaker (consolidated: transitions counter + state gauge)
+          { name: :e11y_circuit_breaker_transitions_total, tags: %i[adapter event] },
+          { name: :e11y_circuit_breaker_state, type: :gauge, tags: [:adapter] },
+          # Adapter performance & reliability
+          { name: :e11y_adapter_send_duration_seconds, type: :histogram, tags: [:adapter], buckets: [0.001, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0] },
+          { name: :e11y_adapter_writes_total, tags: %i[adapter status error_class] },
+          # DLQ
+          { name: :e11y_dlq_size, type: :gauge, tags: [] },
+          { name: :e11y_dlq_filter_decisions_total, tags: %i[action reason] },
+          { name: :e11y_dlq_saved_total, tags: [:event_name] },
+          { name: :e11y_dlq_parse_error_total, tags: [:error] },
+          { name: :e11y_dlq_replayed_total, tags: [:event_name] },
+          { name: :e11y_dlq_replay_failed_total, tags: [:error] },
+          # Retry rate limiter (consolidated)
+          { name: :e11y_retry_rate_limiter_total, tags: %i[adapter event delay_sec] },
+          # Buffer (ring, adaptive) — consolidated
+          { name: :e11y_buffer_overflow_total, tags: [:event] },
+          # Rate limiting / sampling
+          { name: :e11y_events_dropped_total, tags: %i[reason event_type] },
+          # SLO tracking (Request middleware triggers on every HTTP request when enabled)
+          { name: :slo_http_requests_total, tags: %i[controller action status] },
+          { name: :slo_http_request_duration_seconds, type: :histogram, tags: %i[controller action],
+            buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0] },
+          { name: :slo_background_jobs_total, tags: %i[job_class status queue] },
+          { name: :slo_background_job_duration_seconds, type: :histogram, tags: %i[job_class queue],
+            buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0] },
+          # E11y self-monitoring (events tracked at pipeline end)
+          { name: :e11y_events_tracked_total, tags: %i[result event_name] },
+          # Track latency (TrackLatency middleware)
+          { name: :e11y_track_duration_seconds, type: :histogram, tags: %i[event_class severity result],
+            buckets: [0.0001, 0.0005, 0.001, 0.005, 0.01, 0.05, 0.1] }
+        ]
+
+        metrics.each do |m|
+          type = m[:type] || :counter
+          buckets = m[:buckets]
+          register_metric_if_needed(m[:name], type, m[:tags], buckets: buckets)
+        end
+      rescue StandardError => e
+        E11y.logger.debug("Could not register self-monitoring metrics: #{e.message}")
+      end
+
       # Register a single metric in Yabeda
       #
       # @param metric_config [Hash] Metric configuration from Registry
       # @return [void]
-      # rubocop:disable Metrics/MethodLength
       # Metric registration requires case/when for different metric types
       def register_yabeda_metric(metric_config)
         metric_name = metric_config[:name]
         metric_type = metric_config[:type]
         tags = metric_config[:tags] || []
 
+        # Skip if metric already exists (prevents re-registration errors)
+        return if ::Yabeda.metrics.key?("e11y_#{metric_name}")
+
         # Define metric in Yabeda group
-        ::Yabeda.configure do
-          group :e11y do
+        ::Yabeda.configure do |config = nil|
+          next unless config.respond_to?(:group)
+
+          config.group :e11y do
             case metric_type
             when :counter
               counter metric_name, tags: tags, comment: "E11y metric: #{metric_name}"
@@ -309,7 +411,6 @@ module E11y
         # Metric might already be registered - that's OK
         warn "E11y Yabeda: Could not register metric #{metric_name}: #{e.message}"
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Register a metric if it doesn't exist yet (for direct metric calls).
       #
@@ -319,14 +420,15 @@ module E11y
       # @param buckets [Array<Numeric>, nil] Optional histogram buckets
       # @return [void]
       # @api private
-      # rubocop:disable Metrics/MethodLength
       # Metric registration requires case/when for different metric types
       def register_metric_if_needed(name, type, tags, buckets: nil)
-        # Check if metric already exists
-        return if ::Yabeda.metrics.key?(:"e11y_#{name}")
+        # Check if metric already exists (Yabeda stores metric keys as strings)
+        return if ::Yabeda.metrics.key?("e11y_#{name}")
 
-        ::Yabeda.configure do
-          group :e11y do
+        ::Yabeda.configure do |config = nil|
+          next unless config.respond_to?(:group)
+
+          config.group :e11y do
             case type
             when :counter
               counter name, tags: tags, comment: "E11y self-monitoring: #{name}"
@@ -347,38 +449,60 @@ module E11y
         # Metric might already be registered - that's OK
         E11y.logger.warn("Could not register Yabeda metric #{name}: #{e.message}")
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Update a single metric based on event data
       #
       # @param metric_config [Hash] Metric configuration
       # @param event_data [Hash] Event data
       # @return [void]
-      # rubocop:disable Metrics/AbcSize
       # Metric update requires multiple steps for label extraction and value handling
       def update_metric(metric_config, event_data)
         metric_name = metric_config[:name]
         labels = extract_labels(metric_config, event_data)
 
-        # Apply cardinality protection
-        safe_labels = @cardinality_protection.filter(labels, metric_name)
+        # Apply cardinality protection (normalize metric_name to string for consistent tracking)
+        safe_labels = @cardinality_protection.filter(labels, metric_name.to_s)
 
         # Extract value for histogram/gauge
         value = extract_value(metric_config, event_data) if %i[histogram gauge].include?(metric_config[:type])
 
-        # Update Yabeda metric
+        # Get original tags from metric config - these are the tags the metric was registered with
+        original_tags = metric_config.fetch(:tags, [])
+
+        # Lazy registration: register metric if it doesn't exist in Yabeda yet
+        # CRITICAL: Use ORIGINAL tags from metric config, not filtered safe_labels.keys
+        # Prometheus requires all tags declared at registration time
+        register_metric_if_needed(
+          metric_name,
+          metric_config[:type],
+          original_tags,
+          buckets: metric_config[:buckets]
+        )
+
+        # Ensure all required tags are present in safe_labels
+        # If cardinality protection dropped a tag, add placeholder value
+        # Prometheus requires all tags declared at registration to be present in every update
+        final_labels = original_tags.to_h do |tag|
+          [tag, safe_labels.key?(tag) ? safe_labels[tag] : "[DROPPED]"]
+        end
+
+        # Update Yabeda metric (skip if e11y group not registered, e.g. Yabeda not configured)
+        return unless ::Yabeda.respond_to?(:e11y)
+
+        metric = ::Yabeda.e11y.send(metric_name)
+        return unless metric
+
         case metric_config[:type]
         when :counter
-          ::Yabeda.e11y.send(metric_name).increment(safe_labels)
+          metric.increment(final_labels)
         when :histogram
-          ::Yabeda.e11y.send(metric_name).measure(safe_labels, value)
+          metric.measure(final_labels, value)
         when :gauge
-          ::Yabeda.e11y.send(metric_name).set(safe_labels, value)
+          metric.set(final_labels, value)
         end
       rescue StandardError => e
         warn "E11y Yabeda: Error updating metric #{metric_name}: #{e.message}"
       end
-      # rubocop:enable Metrics/AbcSize
 
       # Extract labels from event data
       #

data/lib/e11y/buffers/adaptive_buffer.rb

@@ -247,7 +247,6 @@ module E11y
       #
       # @param obj [Object] Payload object
       # @return [Integer] Size in bytes
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
       def calculate_payload_size(obj)
         case obj
         when String
@@ -266,14 +265,12 @@ module E11y
       rescue StandardError
         500 # Fallback for errors
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
 
       # Handle memory exhaustion according to strategy
       #
       # @param event_data [Hash] Event that caused exhaustion
       # @param event_size [Integer] Size of event
       # @return [Boolean] true if event was eventually added, false if dropped
-      # rubocop:disable Metrics/MethodLength
       def handle_memory_exhaustion(event_data, event_size)
         case @backpressure_strategy
         when :block
@@ -288,7 +285,7 @@ module E11y
             # Check timeout
             if Time.now - wait_start > @max_block_time
               # Timeout exceeded - drop event
-              increment_metric("e11y.buffer.memory_exhaustion.dropped")
+              E11y::Metrics.increment(:e11y_buffer_overflow_total, event: "memory_exhaustion_dropped")
               return false
             end
 
@@ -297,16 +294,15 @@ module E11y
           end
 
           # Space available - retry add
-          increment_metric("e11y.buffer.memory_exhaustion.blocked")
+          E11y::Metrics.increment(:e11y_buffer_overflow_total, event: "memory_exhaustion_blocked")
           add_event(event_data)
 
         when :drop
           # Drop new event
-          increment_metric("e11y.buffer.memory_exhaustion.dropped")
+          E11y::Metrics.increment(:e11y_buffer_overflow_total, event: "memory_exhaustion_dropped")
           false
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Trigger early flush (80% threshold reached)
       #
@@ -323,16 +319,6 @@ module E11y
         warn "E11y: Early flush callback failed: #{e.message}"
       end
 
-      # Increment metric (placeholder for Phase 3: Metrics)
-      #
-      # TODO Phase 3: Replace with actual Yabeda metrics
-      #
-      # @param metric_name [String] Metric to increment
-      # @return [void]
-      def increment_metric(metric_name)
-        # Placeholder - will be implemented in Phase 3
-        # Yabeda.e11y.buffer_memory_exhaustion.increment(strategy: @backpressure_strategy)
-      end
       # rubocop:enable Metrics/ClassLength
     end
   end