e11y 0.2.0 → 1.0.0

data/docs/{ADR-008-rails-integration.md → architecture/ADR-008-rails-integration.md}

@@ -204,24 +204,12 @@ module E11y
       next unless E11y.config.enabled
       
       # Setup instruments (each can be enabled/disabled separately)
-      if E11y.config.instruments.active_support_notifications.enabled
-        E11y::Instruments::ActiveSupportNotifications.setup!
-      end
-      
-      if E11y.config.instruments.sidekiq.enabled
-        E11y::Instruments::Sidekiq.setup!
-      end
-      
-      if E11y.config.instruments.active_job.enabled
-        E11y::Instruments::ActiveJob.setup!
-      end
-      
-      if E11y.config.instruments.rack_middleware.enabled
-        E11y::Instruments::RackMiddleware.setup!
-      end
+      E11y::Railtie.setup_rails_instrumentation if E11y.config.rails_instrumentation&.enabled
+      E11y::Railtie.setup_sidekiq if defined?(::Sidekiq) && E11y.config.sidekiq&.enabled
+      E11y::Railtie.setup_active_job if defined?(::ActiveJob) && E11y.config.active_job&.enabled
       
       # Setup logger bridge
-      E11y::Logger::Bridge.setup! if E11y.config.logger_bridge.enabled
+      E11y::Logger::Bridge.setup! if E11y.config.logger_bridge_enabled
       
       # Setup development tools
       E11y::Console.setup! if Rails.env.development?
@@ -400,7 +388,7 @@ module E11y
       # ========================================
       
       def self.setup!
-        return unless E11y.config.instruments.rails_instrumentation.enabled
+        return unless E11y.config.rails_instrumentation&.enabled
         
         # Subscribe to Rails events
         event_mapping.each do |asn_pattern, e11y_event_class|
@@ -433,6 +421,7 @@ module E11y
         'enqueue.active_job' => Events::Rails::Job::Enqueued,
         'enqueue_at.active_job' => Events::Rails::Job::Scheduled,
         'perform_start.active_job' => Events::Rails::Job::Started,
+        # perform.active_job: Completed on success; Failed when payload has exception
         'perform.active_job' => Events::Rails::Job::Completed
       }.freeze
       
@@ -442,7 +431,7 @@ module E11y
           mapping = DEFAULT_RAILS_EVENT_MAPPING.dup
           
           # Apply custom mappings from config (Devise-style overrides)
-          custom_mappings = E11y.config.instruments.rails_instrumentation.custom_mappings || {}
+          custom_mappings = E11y.config.rails_instrumentation&.custom_mappings || {}
           mapping.merge!(custom_mappings)
           
           mapping
@@ -450,7 +439,7 @@ module E11y
       end
       
       def self.ignored?(pattern)
-        ignore_list = E11y.config.instruments.rails_instrumentation.ignore_events || []
+        ignore_list = E11y.config.rails_instrumentation&.ignore_events || []
         ignore_list.include?(pattern)
       end
       
@@ -477,62 +466,60 @@ end
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.instruments do
+  # ========================================
+  # Rails Instrumentation (ActiveSupport::Notifications → E11y)
+  # ========================================
+  config.rails_instrumentation do
+    # Enable/disable entire ASN integration
+    enabled true  # Set to false to completely disable
+    
+    # Built-in event classes (auto-created by E11y)
+    # Located in Events::Rails namespace
+    use_built_in_events true  # If false, no auto-mapping
+    
     # ========================================
-    # Rails Instrumentation (ActiveSupport::Notifications → E11y)
+    # OVERRIDE EVENT CLASSES (Devise-style)
     # ========================================
-    rails_instrumentation do
-      # Enable/disable entire ASN integration
-      enabled true  # Set to false to completely disable
-      
-      # Built-in event classes (auto-created by E11y)
-      # Located in Events::Rails namespace
-      use_built_in_events true  # If false, no auto-mapping
-      
-      # ========================================
-      # OVERRIDE EVENT CLASSES (Devise-style)
-      # ========================================
-      
-      # Override default event class for specific ASN pattern
-      event_class_for 'sql.active_record', MyApp::Events::CustomDatabaseQuery
-      event_class_for 'process_action.action_controller', MyApp::Events::CustomHttpRequest
-      
-      # Disable specific events (too noisy or not needed)
-      ignore_event 'cache_read.active_support'
-      ignore_event 'render_partial.action_view'
-      ignore_event 'SCHEMA'  # Schema queries
-      
-      # ========================================
-      # SELECTIVE INSTRUMENTATION
-      # ========================================
-      
-      # Which Rails events to track (glob patterns)
-      track_patterns [
-        'sql.active_record',
-        'process_action.action_controller',
-        'render_template.action_view',
-        'cache_*.active_support'
-      ]
-      
-      # Sampling for high-volume events
-      sample_patterns do
-        pattern 'sql.active_record', sample_rate: 0.1  # 10% of SQL queries
-        pattern 'cache_read.active_support', sample_rate: 0.01  # 1% of cache reads
-      end
-      
-      # Enrich with custom data
-      enrich do |asn_event|
-        {
-          controller: asn_event.payload[:controller],
-          action: asn_event.payload[:action],
-          format: asn_event.payload[:format],
-          user_id: Current.user&.id  # Add context
-        }
-      end
+    
+    # Override default event class for specific ASN pattern
+    event_class_for 'sql.active_record', MyApp::Events::CustomDatabaseQuery
+    event_class_for 'process_action.action_controller', MyApp::Events::CustomHttpRequest
+    
+    # Disable specific events (too noisy or not needed)
+    ignore_event 'cache_read.active_support'
+    ignore_event 'render_partial.action_view'
+    ignore_event 'SCHEMA'  # Schema queries
+    
+    # ========================================
+    # SELECTIVE INSTRUMENTATION
+    # ========================================
+    
+    # Which Rails events to track (glob patterns)
+    track_patterns [
+      'sql.active_record',
+      'process_action.action_controller',
+      'render_template.action_view',
+      'cache_*.active_support'
+    ]
+    
+    # Sampling for high-volume events
+    sample_patterns do
+      pattern 'sql.active_record', sample_rate: 0.1  # 10% of SQL queries
+      pattern 'cache_read.active_support', sample_rate: 0.01  # 1% of cache reads
     end
     
-    # (Other integrations: Sidekiq, ActiveJob, etc.)
+    # Enrich with custom data
+    enrich do |asn_event|
+      {
+        controller: asn_event.payload[:controller],
+        action: asn_event.payload[:action],
+        format: asn_event.payload[:format],
+        user_id: Current.user&.id  # Add context
+      }
+    end
   end
+  
+  # (Other integrations: config.sidekiq, config.active_job, config.logger_bridge)
 end
 ```
 
@@ -580,7 +567,7 @@ end
 
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.instruments.rails_instrumentation do
+  config.rails_instrumentation do
     # Override default event class
     event_class_for 'sql.active_record', MyApp::Events::CustomDatabaseQuery
   end
@@ -660,71 +647,44 @@ module E11y
 end
 ```
     
-    # ========================================
-    # Sidekiq
-    # ========================================
-    sidekiq do
-      enabled true  # Set to false to disable Sidekiq integration
-      
-      # Server middleware (job execution)
-      server_middleware do
-        enabled true
-        track_start true
-        track_complete true
-        track_failure true
-      end
-      
-      # Client middleware (job enqueuing)
-      client_middleware do
-        enabled true
-        track_enqueue true
-      end
-      
-      # Trace propagation
-      propagate_trace_context true
-      trace_context_keys ['e11y_trace_id', 'e11y_span_id', 'e11y_sampled']
-    end
+  # ========================================
+  # Sidekiq
+  # ========================================
+  config.sidekiq do
+    enabled true  # Set to false to disable Sidekiq integration
     
-    # ========================================
-    # ActiveJob
-    # ========================================
-    active_job do
-      enabled true  # Set to false to disable ActiveJob integration
-      
-      track_enqueue true
+    # Server middleware (job execution)
+    server_middleware do
+      enabled true
       track_start true
       track_complete true
       track_failure true
-      
-      # Trace propagation
-      propagate_trace_context true
-      
-      # Job-scoped buffer (like request-scoped buffer for HTTP)
-      use_job_buffer true
-      
-      job_buffer do
-        buffer_severities [:debug]
-        flush_on do
-          error true       # Flush debug events if job fails
-          success false    # Discard debug events if job succeeds
-        end
-        max_events 1000
-      end
     end
     
-    # ========================================
-    # Rack Middleware
-    # ========================================
-    rack_middleware do
-      enabled true  # Set to false to disable Rack middleware
-      
-      track_request_start true
-      track_request_complete true
-      track_request_failure true
-      
-      # Request-scoped buffer
-      use_request_buffer true
+    # Client middleware (job enqueuing)
+    client_middleware do
+      enabled true
+      track_enqueue true
     end
+    
+    # Trace propagation (C17 hybrid: job gets NEW trace_id, links via e11y_parent_trace_id)
+    propagate_trace_context true
+    trace_context_keys ['e11y_parent_trace_id', 'e11y_span_id', 'e11y_sampled']
+  end
+  
+  # ========================================
+  # ActiveJob
+  # ========================================
+  config.active_job do
+    enabled true  # Set to false to disable ActiveJob integration
+    
+    track_enqueue true
+    track_start true
+    track_complete true
+    track_failure true
+    
+    # Trace propagation
+    propagate_trace_context true
   end
 end
 ```
@@ -734,19 +694,16 @@ end
 ```ruby
 # Disable ASN but keep Sidekiq
 E11y.configure do |config|
-  config.instruments.active_support_notifications.enabled = false
-  config.instruments.sidekiq.enabled = true
-  config.instruments.active_job.enabled = true
+  config.rails_instrumentation_enabled = false
+  config.sidekiq_enabled = true
+  config.active_job_enabled = true
 end
 
 # Minimal setup: only Sidekiq
 E11y.configure do |config|
-  config.instruments do
-    active_support_notifications { enabled false }
-    sidekiq { enabled true }
-    active_job { enabled false }
-    rack_middleware { enabled false }
-  end
+  config.rails_instrumentation_enabled = false
+  config.sidekiq_enabled = true
+  config.active_job_enabled = false
 end
 ```
 
@@ -860,7 +817,7 @@ end
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.instruments.active_support_notifications do
+  config.rails_instrumentation do
     # Disable built-in events
     use_built_in_events false
     
@@ -877,6 +834,8 @@ end
 
 ## 5. Sidekiq Integration
 
+**Implementation Note:** Sidekiq middleware emits `Events::Rails::Job::Enqueued`, `Started`, `Completed`, `Failed` for **raw Sidekiq jobs only** (`include Sidekiq::Worker`). When Sidekiq is the queue adapter for ActiveJob, jobs use `ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper`; we skip event emission in Sidekiq middleware to avoid double emission — ActiveJob events come from RailsInstrumentation (ASN).
+
 ### 5.1. Server Middleware (Job Execution)
 
 ```ruby
@@ -886,22 +845,25 @@ module E11y
     module Sidekiq
       class ServerMiddleware
         def call(worker, job, queue)
-          # Extract trace context from job metadata
-          trace_id = job['e11y_trace_id'] || E11y::TraceContext.generate_id
+          # C17 Hybrid: Job gets NEW trace_id, parent_trace_id links to enqueuing request
+          parent_trace_id = job['e11y_parent_trace_id']
+          trace_id = E11y::TraceContext.generate_id  # NEW trace per job
           parent_span_id = job['e11y_span_id']
           
-          # Restore trace context
           E11y::Current.set(
             trace_id: trace_id,
+            parent_trace_id: parent_trace_id,
             parent_span_id: parent_span_id,
             job_id: job['jid'],
             job_class: worker.class.name,
             queue: queue
           )
           
-          # Start job-scoped buffer (optional, configurable)
-          if E11y.config.instruments.sidekiq.use_job_buffer
-            E11y::JobBuffer.start!
+          # Start request-scoped buffer (same as HTTP; config.ephemeral_buffer_enabled)
+          if E11y.config.ephemeral_buffer_enabled
+            limit = E11y.config.ephemeral_buffer_job_buffer_limit ||
+                    E11y::Buffers::EphemeralBuffer::DEFAULT_BUFFER_LIMIT
+            E11y::EphemeralBuffer.initialize!(buffer_limit: limit)
           end
           
           # Track job start
@@ -926,8 +888,8 @@ module E11y
               queue: queue
             )
             
-            # Flush job buffer (success case)
-            E11y::JobBuffer.flush! if E11y.config.instruments.sidekiq.use_job_buffer
+            # Discard buffer on success (same as HTTP)
+            E11y::EphemeralBuffer.discard if E11y.config.ephemeral_buffer_enabled
             
             result
           rescue => error
@@ -942,8 +904,8 @@ module E11y
               backtrace: error.backtrace&.first(10)
             )
             
-            # Flush job buffer on error (includes debug events)
-            E11y::JobBuffer.flush_on_error! if E11y.config.instruments.sidekiq.use_job_buffer
+            # Flush buffer on error (includes debug events)
+            E11y::EphemeralBuffer.flush_on_error if E11y.config.ephemeral_buffer_enabled
             
             raise
           ensure
@@ -976,8 +938,8 @@ module E11y
     module Sidekiq
       class ClientMiddleware
         def call(worker_class, job, queue, redis_pool)
-          # Propagate trace context to job
-          job['e11y_trace_id'] = E11y::Current.trace_id
+          # C17 Hybrid: Propagate parent trace (job will create NEW trace_id)
+          job['e11y_parent_trace_id'] = E11y::Current.trace_id if E11y::Current.trace_id
           job['e11y_span_id'] = E11y::TraceContext.generate_span_id
           job['e11y_sampled'] = E11y::Current.sampled  # Trace-consistent sampling
           
@@ -997,89 +959,22 @@ module E11y
 end
 ```
 
-### 5.3. Job-Scoped Buffer (Optional Feature)
+### 5.3. Buffer for Jobs
 
-**Design Decision:** Similar to request-scoped buffer, jobs can have their own buffer for debug events.
+**Design Decision:** Jobs reuse the same `EphemeralBuffer` as HTTP requests. Same semantics: buffer debug events, flush on error, discard on success. Optional job-specific config allows tuning for longer-running jobs.
 
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.instruments.sidekiq do
-    # Enable job-scoped buffer (like request-scoped buffer)
-    use_job_buffer true
-    
-    job_buffer do
-      # Buffer debug events during job execution
-      buffer_severities [:debug]
-      
-      # Flush conditions
-      flush_on do
-        error true           # Flush debug events if job fails
-        success false        # Discard debug events if job succeeds
-        interval 5.seconds   # Or flush every 5 seconds
-      end
-      
-      # Max buffer size per job
-      max_events 1000
-    end
-  end
-end
-```
-
-**How it works:**
-
-```ruby
-class InvoiceGenerationWorker
-  include Sidekiq::Worker
+  # Shared buffer for HTTP and jobs
+  config.ephemeral_buffer_enabled = true
   
-  def perform(order_id)
-    # Debug events are buffered
-    Events::Debug::FetchOrder.track(order_id: order_id)
-    
-    order = Order.find(order_id)
-    
-    Events::Debug::ValidateOrder.track(order_id: order_id, valid: order.valid?)
-    
-    if order.invalid?
-      # Job fails → debug events are flushed to adapters
-      raise "Invalid order"
-    end
-    
-    # Job succeeds → debug events are discarded
-    Events::InvoiceGenerated.track(order_id: order_id)
-  end
+  # Optional: job-specific overrides (jobs can run longer → more debug events)
+  config.ephemeral_buffer_job_buffer_limit = 500  # nil = use default (100)
 end
 ```
 
-**Job Buffer Lifecycle:**
-
-```mermaid
-sequenceDiagram
-    participant Worker as Sidekiq Worker
-    participant JobBuffer as Job Buffer
-    participant MainBuffer as Main Buffer
-    participant Adapters as Adapters
-    
-    Worker->>JobBuffer: Start job buffer
-    
-    Note over Worker: Job execution starts
-    
-    Worker->>JobBuffer: Track debug event
-    JobBuffer->>JobBuffer: Buffer (not flushed)
-    
-    Worker->>MainBuffer: Track info event
-    MainBuffer->>Adapters: Flush immediately (normal flow)
-    
-    alt Job succeeds
-        Worker->>JobBuffer: flush! (success)
-        JobBuffer->>JobBuffer: Discard debug events
-        Note over JobBuffer: Debug events never sent
-    else Job fails
-        Worker->>JobBuffer: flush_on_error!
-        JobBuffer->>MainBuffer: Move debug events to main buffer
-        MainBuffer->>Adapters: Flush all events (including debug)
-    end
-```
+**Rationale:** Single buffer implementation, single config. Jobs may need higher `job_buffer_limit` when they process many items and emit more debug events than a typical HTTP request.
 
 ---
 
@@ -1100,21 +995,21 @@ sequenceDiagram
     ClientMW->>ClientMW: Extract trace_id from Current
     ClientMW->>Redis: Store job + trace metadata
     
-    Note over Redis: job['e11y_trace_id'] = 'abc123'<br/>job['e11y_span_id'] = 'span002'<br/>job['e11y_sampled'] = true
+    Note over Redis: job['e11y_parent_trace_id'] = 'abc123'<br/>job['e11y_span_id'] = 'span002'<br/>job['e11y_sampled'] = true
     
     ClientMW->>E11y: Track Enqueued event
     
     Note over ServerMW: Later... job dequeued
     
     Redis->>ServerMW: Fetch job
-    ServerMW->>ServerMW: Extract trace_id from job
+    ServerMW->>ServerMW: C17: new trace_id, parent_trace_id from job
     ServerMW->>E11y: Restore Current context
     
-    Note over E11y: Current.trace_id = 'abc123'<br/>Current.parent_span_id = 'span002'
+    Note over E11y: Current.trace_id = NEW<br/>Current.parent_trace_id = 'abc123'<br/>Current.parent_span_id = 'span002'
     
     ServerMW->>E11y: Track Started event
     ServerMW->>Worker: perform
-    Worker->>E11y: Track custom events (same trace_id!)
+    Worker->>E11y: Track events (linked via parent_trace_id!)
     ServerMW->>E11y: Track Completed event
 ```
 
@@ -1122,6 +1017,13 @@ sequenceDiagram
 
 ## 6. ActiveJob Integration
 
+**Implementation Note:** Job lifecycle events (`Enqueued`, `Started`, `Completed`, `Failed`) come from **RailsInstrumentation** (ASN), not from ActiveJob callbacks. ActiveJob callbacks handle trace context propagation, request-scoped buffer, and SLO tracking only. This design:
+- Uses ASN as single source for all queue adapters (Sidekiq, Resque, Solid Queue, etc.)
+- Avoids duplicate emission when ActiveJob uses Sidekiq as adapter
+- Keeps callbacks focused on context/buffer/SLO
+
+**perform.active_job routing:** When payload contains `exception`, RailsInstrumentation routes to `Events::Rails::Job::Failed` (with `error_class`, `error_message`); otherwise to `Completed`.
+
 ### 6.1. Callbacks Integration
 
 ```ruby
@@ -1140,20 +1042,24 @@ module E11y
         private
         
         def e11y_track_job_execution
-          # Extract trace context
-          trace_id = job_metadata['e11y_trace_id'] || E11y::TraceContext.generate_id
+          # C17 Hybrid: Job gets NEW trace_id, parent_trace_id links to enqueuer
+          parent_trace_id = job_metadata['e11y_parent_trace_id']
+          trace_id = E11y::TraceContext.generate_id
           parent_span_id = job_metadata['e11y_span_id']
           
           E11y::Current.set(
             trace_id: trace_id,
+            parent_trace_id: parent_trace_id,
             parent_span_id: parent_span_id,
             job_id: job_id,
             job_class: self.class.name
           )
           
-          # Start job-scoped buffer (optional, configurable)
-          if E11y.config.instruments.active_job.use_job_buffer
-            E11y::JobBuffer.start!
+          # Start request-scoped buffer (same as HTTP; config.ephemeral_buffer_enabled)
+          if E11y.config.ephemeral_buffer_enabled
+            limit = E11y.config.ephemeral_buffer_job_buffer_limit ||
+                    E11y::Buffers::EphemeralBuffer::DEFAULT_BUFFER_LIMIT
+            E11y::EphemeralBuffer.initialize!(buffer_limit: limit)
           end
           
           Events::Rails::Job::Started.track(
@@ -1174,8 +1080,8 @@ module E11y
               duration: (Time.now - start_time) * 1000
             )
             
-            # Flush job buffer (success case)
-            E11y::JobBuffer.flush! if E11y.config.instruments.active_job.use_job_buffer
+            # Discard buffer on success (same as HTTP)
+            E11y::EphemeralBuffer.discard if E11y.config.ephemeral_buffer_enabled
           rescue => error
             Events::Rails::Job::Failed.track(
               job_class: self.class.name,
@@ -1185,8 +1091,8 @@ module E11y
               error_message: error.message
             )
             
-            # Flush job buffer on error (includes debug events)
-            E11y::JobBuffer.flush_on_error! if E11y.config.instruments.active_job.use_job_buffer
+            # Flush buffer on error (includes debug events)
+            E11y::EphemeralBuffer.flush_on_error if E11y.config.ephemeral_buffer_enabled
             
             raise
           ensure
@@ -1195,8 +1101,8 @@ module E11y
         end
         
         def e11y_track_job_enqueued
-          # Store trace context in job metadata
-          job_metadata['e11y_trace_id'] = E11y::Current.trace_id
+          # C17 Hybrid: Store parent trace (job will create NEW trace_id)
+          job_metadata['e11y_parent_trace_id'] = E11y::Current.trace_id if E11y::Current.trace_id
           job_metadata['e11y_span_id'] = E11y::TraceContext.generate_span_id
           job_metadata['e11y_sampled'] = E11y::Current.sampled
           
@@ -1235,7 +1141,7 @@ module E11y
   module Logger
     class Bridge
       def self.setup!
-        return unless E11y.config.logger_bridge.enabled
+        return unless E11y.config.logger_bridge_enabled
         
         # Replace Rails.logger
         Rails.logger = Bridge.new(Rails.logger)
@@ -1304,17 +1210,10 @@ module E11y
         # Extract message
         msg = message || (block_given? ? block.call : nil)
         
-        # Track via E11y
-        Events::RailsLogger.track(
-          severity: severity,
-          message: msg.to_s,
-          caller_location: extract_caller_location
-        )
+        # Track via E11y (filtered by track_severities, ignore_patterns)
+        event_class_for_severity(severity).track(message: msg.to_s, caller_location: extract_caller_location)
         
-        # Also log to original logger (dual logging)
-        if @original_logger && E11y.config.logger_bridge.dual_logging
-          @original_logger.public_send(severity, msg)
-        end
+        # Always delegate to original logger (SimpleDelegator super)
       end
       
       def extract_caller_location
@@ -1330,50 +1229,39 @@ module E11y
 end
 ```
 
-### 7.2. Migration Strategy
+### 7.2. Configuration
 
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.logger_bridge do
-    enabled true
-    
-    # Dual logging (E11y + original Rails.logger)
-    dual_logging true  # Keep writing to log/production.log
-    
-    # Which severities to track
-    track_severities [:info, :warn, :error, :fatal]
-    
-    # Skip noisy log messages
-    ignore_patterns [
-      /Started GET/,
-      /Completed \d+ OK/,
-      /CACHE/
-    ]
-    
-    # Sample high-volume logs
-    sample_rate 0.1  # 10% of logs
-    
-    # Enrich with Rails context
-    enrich_with_context true
-    context_fields [:controller, :action, :request_id]
-  end
+  config.logger_bridge_enabled = true
+  
+  # Which severities to track (nil = all)
+  config.logger_bridge_track_severities = [:info, :warn, :error, :fatal]
+  
+  # Skip noisy log messages (regex or string)
+  config.logger_bridge_ignore_patterns = [
+    /Started GET/,
+    /Completed \d+ OK/,
+    /CACHE/
+  ]
 end
 ```
 
+**Context:** Events are enriched with `trace_id`, `request_id`, `span_id`, `user_id` from `E11y::Current` via `Event::Base.build_context` — no separate config needed.
+
 ---
 
 ## 8. Middleware Integration
 
-### 8.0. Three Buffer Types (Summary)
+### 8.0. Buffer Types (Summary)
 
-**E11y has 3 independent buffer types:**
+**E11y uses a single EphemeralBuffer for both HTTP and jobs:**
 
-| Buffer Type | Purpose | Lifecycle | Use Case |
-|-------------|---------|-----------|----------|
-| **Main Buffer** | All events (info+) | Global, flush every 200ms | Normal event tracking |
-| **Request Buffer** | Debug events in HTTP requests | Per-request, flush on error | HTTP request debugging |
-| **Job Buffer** | Debug events in background jobs | Per-job, flush on error | Background job debugging |
+| Buffer | Purpose | Lifecycle | Config |
+|--------|---------|-----------|--------|
+| **Request Buffer** | Debug events (HTTP + jobs) | Per-request/job, flush on error, discard on success | `config.ephemeral_buffer_enabled`, `ephemeral_buffer_job_buffer_limit` |
+| **Main Buffer** | All events (info+) | Global, flush every 200ms | — |
 
 **Diagram:**
 
@@ -1381,20 +1269,20 @@ end
 graph TB
     subgraph "HTTP Request"
         HTTPEvent[Event tracked] --> Decision1{Severity?}
-        Decision1 -->|:debug| RequestBuffer[Request Buffer]
+        Decision1 -->|:debug| [Request Buffer]
         Decision1 -->|:info+| MainBuffer[Main Buffer]
         
-        RequestBuffer --> OnError1{Request failed?}
+         --> OnError1{Request failed?}
         OnError1 -->|Yes| MainBuffer
         OnError1 -->|No| Discard1[Discard]
     end
     
     subgraph "Background Job"
         JobEvent[Event tracked] --> Decision2{Severity?}
-        Decision2 -->|:debug| JobBuffer[Job Buffer]
+        Decision2 -->|:debug| 
         Decision2 -->|:info+| MainBuffer2[Main Buffer]
         
-        JobBuffer --> OnError2{Job failed?}
+         --> OnError2{Job failed?}
         OnError2 -->|Yes| MainBuffer2
         OnError2 -->|No| Discard2[Discard]
     end
@@ -1405,8 +1293,7 @@ graph TB
         Interval --> Adapters[Flush to Adapters]
     end
     
-    style RequestBuffer fill:#fff3cd
-    style JobBuffer fill:#d4edda
+    style  fill:#fff3cd
     style MainBuffer fill:#d1ecf1
     style MainBuffer2 fill:#d1ecf1
 ```
@@ -1415,16 +1302,9 @@ graph TB
 
 ```ruby
 E11y.configure do |config|
-  # Main buffer (always enabled)
-  config.buffer.flush_interval = 200.milliseconds
-  config.buffer.max_size = 10_000
-  
-  # Request-scoped buffer (HTTP only)
-  config.instruments.rack_middleware.use_request_buffer = true
-  
-  # Job-scoped buffer (Sidekiq + ActiveJob)
-  config.instruments.sidekiq.use_job_buffer = true
-  config.instruments.active_job.use_job_buffer = true
+  # Request-scoped buffer (shared for HTTP and jobs)
+  config.ephemeral_buffer_enabled = true
+  config.ephemeral_buffer_job_buffer_limit = 500  # Optional: higher limit for jobs (nil = default 100)
 end
 ```
 
@@ -1458,12 +1338,8 @@ module E11y
           user_agent: request.user_agent
         )
         
-        # Start request-scoped buffer (for debug events)
-        # Note: This is ONLY for HTTP requests, not for jobs
-        # Jobs have their own JobBuffer (see Sidekiq/ActiveJob sections)
-        if E11y.config.instruments.rack_middleware.use_request_buffer
-          E11y::RequestBuffer.start!
-        end
+        # Start request-scoped buffer (for debug events; shared with jobs)
+        E11y::EphemeralBuffer.initialize! if E11y.config.ephemeral_buffer&.enabled
         
         # Track request start
         start_time = Time.now
@@ -1501,17 +1377,13 @@ module E11y
             error_message: error.message
           )
           
-          # Flush request buffer (includes debug events on error)
-          if E11y.config.instruments.rack_middleware.use_request_buffer
-            E11y::RequestBuffer.flush_on_error!
-          end
+          # Flush buffer on error (includes debug events)
+          E11y::EphemeralBuffer.flush_on_error if E11y.config.ephemeral_buffer&.enabled
           
           raise
         ensure
-          # Flush request buffer (success case)
-          if E11y.config.instruments.rack_middleware.use_request_buffer && !error
-            E11y::RequestBuffer.flush!
-          end
+          # Discard buffer on success (not on error; already flushed in rescue)
+          E11y::EphemeralBuffer.discard if !$ERROR_INFO && E11y.config.ephemeral_buffer&.enabled
           
           # Reset context
           Current.reset
@@ -1563,10 +1435,10 @@ module E11y
       # E11y.stats
       def E11y.stats
         {
-          events_tracked: Registry.all_events.sum { |e| e.track_count },
+          events_tracked: Registry.event_classes.sum { |e| e.track_count },
           events_in_buffer: Buffer.size,
-          adapters: Adapters::Registry.all.map { |a| 
-            { name: a.name, healthy: a.healthy? }
+          adapters: config.adapters.map { |name, a|
+            { name: name, healthy: a.respond_to?(:healthy?) ? a.healthy? : true }
           },
           rate_limiter: {
             current_rate: RateLimiter.current_rate,
@@ -1588,17 +1460,17 @@ module E11y
       
       # E11y.events
       def E11y.events
-        Registry.all_events.map(&:name).sort
+        Registry.event_classes.map(&:name).sort
       end
       
       # E11y.adapters
       def E11y.adapters
-        Adapters::Registry.all.map do |adapter|
+        config.adapters.map do |name, adapter|
           {
-            name: adapter.name,
+            name: name,
             class: adapter.class.name,
-            healthy: adapter.healthy?,
-            capabilities: adapter.capabilities
+            healthy: adapter.respond_to?(:healthy?) ? adapter.healthy? : true,
+            capabilities: adapter.respond_to?(:capabilities) ? adapter.capabilities : {}
           }
         end
       end
@@ -1606,7 +1478,7 @@ module E11y
       # E11y.reset!
       def E11y.reset!
         Buffer.clear!
-        RequestBuffer.clear!
+        .clear!
         puts "✅ Buffers cleared"
       end
     end
@@ -1621,7 +1493,7 @@ module E11y
         )
         
         # Disable rate limiting in console
-        config.rate_limiting.enabled = false
+        config.rate_limiting_enabled = false
         
         # Show all severities
         config.severity_threshold = :debug
@@ -1772,7 +1644,7 @@ RSpec.describe OrdersController, type: :controller do
       }.to have_enqueued_job(SendOrderEmailJob)
       
       job = ActiveJob::Base.queue_adapter.enqueued_jobs.last
-      expect(job[:args].first['e11y_trace_id']).to be_present
+      expect(job[:args].first['e11y_parent_trace_id']).to be_present
     end
   end
 end
@@ -1819,10 +1691,10 @@ end
 
 ```ruby
 E11y.configure do |config|
-  config.instruments.active_support_notifications.enabled = false  # Disable ASN
-  config.instruments.sidekiq.enabled = true                       # Keep Sidekiq
-  config.instruments.active_job.enabled = true                    # Keep ActiveJob
-  config.instruments.rack_middleware.enabled = true               # Keep HTTP tracking
+  config.rails_instrumentation_enabled = false  # Disable ASN
+  config.sidekiq_enabled = true                # Keep Sidekiq
+  config.active_job_enabled = true              # Keep ActiveJob
+  config.logger_bridge_enabled = true          # Keep logger bridge
 end
 ```
 
@@ -1845,7 +1717,7 @@ end
 **No!** It's configurable:
 
 ```ruby
-config.instruments.active_support_notifications do
+config.rails_instrumentation do
   enabled false  # Completely disable ASN integration
 end
 ```
@@ -1853,26 +1725,24 @@ end
 You can also filter which ASN events to track:
 
 ```ruby
-config.instruments.active_support_notifications do
+config.rails_instrumentation do
   track_patterns ['sql.active_record', 'process_action.*']
-  ignore_patterns ['render_partial.*', 'SCHEMA']
+  ignore_events ['render_partial.*', 'SCHEMA']
 end
 ```
 
 ### Q4: Does request-scoped buffer work for Sidekiq/ActiveJob?
 
-**No, they have their own job-scoped buffer!**
+**Yes. HTTP and jobs share the same EphemeralBuffer.**
 
-- **Request Buffer** → HTTP requests only (Rack middleware)
-- **Job Buffer** → Sidekiq + ActiveJob (separate buffer per job)
+- **Request Buffer** → HTTP requests and jobs (same buffer, same semantics)
 - **Main Buffer** → Global buffer for all info+ events
 
-All 3 buffers are independent and configurable:
+Config:
 
 ```ruby
-config.instruments.rack_middleware.use_request_buffer = true   # HTTP
-config.instruments.sidekiq.use_job_buffer = true              # Sidekiq
-config.instruments.active_job.use_job_buffer = true           # ActiveJob
+config.ephemeral_buffer_enabled = true
+config.ephemeral_buffer_job_buffer_limit = 500  # Optional: higher limit for jobs (nil = default 100)
 ```
 
 ### Q5: How do I customize built-in Rails events?
@@ -1880,7 +1750,7 @@ config.instruments.active_job.use_job_buffer = true           # ActiveJob
 **Option A: Override with custom event class:**
 
 ```ruby
-config.instruments.active_support_notifications do
+config.rails_instrumentation do
   custom_mappings do
     map 'sql.active_record', to: MyApp::Events::CustomDatabaseQuery
   end
@@ -1890,7 +1760,7 @@ end
 **Option B: Disable built-in events entirely:**
 
 ```ruby
-config.instruments.active_support_notifications do
+config.rails_instrumentation do
   use_built_in_events false  # No automatic mapping
   
   # Manually handle ASN events