e11y 0.2.0 → 1.1.0

data/docs/use_cases/UC-005-sentry-integration.md

@@ -12,7 +12,7 @@
 - ✅ Trace context propagation (trace_id, span_id)
 - ✅ User context support
 - ✅ 39 comprehensive tests
-- 📖 See [ADR-004 §4.4](../ADR-004-adapter-architecture.md#44-sentry-adapter) for technical details
+- 📖 See [ADR-004 §4.4](../architecture/ADR-004-adapter-architecture.md#44-sentry-adapter) for technical details
 
 ---
 
@@ -72,23 +72,22 @@ end
 
 ### 1. Automatic Exception Capture
 
-> **Implementation:** See [ADR-004 Section 4.4: Sentry Adapter](../ADR-004-adapter-architecture.md#44-sentry-adapter) for technical details.
+> **Implementation:** See [ADR-004 Section 4.4: Sentry Adapter](../architecture/ADR-004-adapter-architecture.md#44-sentry-adapter) for technical details.
 
 **Configuration (2026-01-19 - Actual Implementation):**
 ```ruby
 # config/initializers/e11y.rb
 require 'e11y'
 
-# Register Sentry adapter
-E11y::Adapters::Registry.register(
-  :sentry,
-  E11y::Adapters::Sentry.new(
+# Configure Sentry adapter
+E11y.configure do |config|
+  config.adapters[:sentry] = E11y::Adapters::Sentry.new(
     dsn: ENV['SENTRY_DSN'],
     environment: Rails.env,
     severity_threshold: :warn,  # Send :warn, :error, :fatal to Sentry
     breadcrumbs: true           # Track all events as breadcrumbs
   )
-)
+end
 
 # Use in events
 class Events::PaymentFailed < E11y::Event::Base
@@ -185,7 +184,7 @@ Events::PaymentFailed.track(
 
 ### 4. Custom Fingerprinting
 
-> **Implementation:** See [ADR-004 Section 4.4: Sentry Adapter](../ADR-004-adapter-architecture.md#44-sentry-adapter) for technical details.
+> **Implementation:** See [ADR-004 Section 4.4: Sentry Adapter](../architecture/ADR-004-adapter-architecture.md#44-sentry-adapter) for technical details.
 
 **Group similar errors in Sentry:**
 ```ruby
@@ -218,7 +217,7 @@ end
 
 ### 5. Sampling Control
 
-> **Implementation:** See [ADR-004 Section 4.4: Sentry Adapter](../ADR-004-adapter-architecture.md#44-sentry-adapter) for technical details.
+> **Implementation:** See [ADR-004 Section 4.4: Sentry Adapter](../architecture/ADR-004-adapter-architecture.md#44-sentry-adapter) for technical details.
 
 **Avoid Sentry quota exhaustion:**
 ```ruby
@@ -699,16 +698,15 @@ The implemented `E11y::Adapters::Sentry` provides:
 
 **Usage Example:**
 ```ruby
-# Register adapter
-E11y::Adapters::Registry.register(
-  :sentry,
-  E11y::Adapters::Sentry.new(
+# Configure adapter
+E11y.configure do |config|
+  config.adapters[:sentry] = E11y::Adapters::Sentry.new(
     dsn: ENV['SENTRY_DSN'],
     environment: 'production',
     severity_threshold: :warn,
     breadcrumbs: true
   )
-)
+end
 
 # Track error event
 Events::PaymentFailed.track(
@@ -750,7 +748,7 @@ end
 **See Also:**
 - Implementation: `lib/e11y/adapters/sentry.rb` (211 lines)
 - Tests: `spec/e11y/adapters/sentry_spec.rb` (39 tests)
-- ADR: [ADR-004 §4.4](../ADR-004-adapter-architecture.md#44-sentry-adapter)
+- ADR: [ADR-004 §4.4](../architecture/ADR-004-adapter-architecture.md#44-sentry-adapter)
 
 ---
 

data/docs/use_cases/UC-006-trace-context-management.md

@@ -42,19 +42,20 @@ Events::PaymentProcessed.track(order_id: '123', amount: 99)
 Events::OrderCreated.track(order_id: '456')
 # → { trace_id: 'def-456', event: 'order.created' }
 
-# Request 1 background job (trace_id: abc-123 - PRESERVED!)
+# Request 1 background job (C17 Hybrid: NEW trace_id xyz-789, parent_trace_id: abc-123)
 Events::EmailSent.track(order_id: '123')
-# → { trace_id: 'abc-123', event: 'email.sent' }
+# → { trace_id: 'xyz-789', parent_trace_id: 'abc-123', event: 'email.sent' }
 
 # In Grafana/Loki:
-# {trace_id="abc-123"} → Shows COMPLETE request timeline across services
+# {trace_id="abc-123"} → Request timeline
+# {trace_id="xyz-789"} or {parent_trace_id="abc-123"} → Job timeline (linked to request)
 ```
 
 ---
 
 ## 🎯 Features
 
-> **Implementation:** See [ADR-005: Tracing Context](../ADR-005-tracing-context.md) for complete architecture, including [Section 3: Current (Thread-Local Storage)](../ADR-005-tracing-context.md#3-current-thread-local-storage), [Section 4: Trace ID Generation](../ADR-005-tracing-context.md#4-trace-id-generation-idgenerator), and [Section 5: W3C Trace Context](../ADR-005-tracing-context.md#5-w3c-trace-context).
+> **Implementation:** See [ADR-005: Tracing Context](../architecture/ADR-005-tracing-context.md) for complete architecture, including [Section 3: Current (Thread-Local Storage)](../architecture/ADR-005-tracing-context.md#3-current-thread-local-storage), [Section 4: Trace ID Generation](../architecture/ADR-005-tracing-context.md#4-trace-id-generation-idgenerator), and [Section 5: W3C Trace Context](../architecture/ADR-005-tracing-context.md#5-w3c-trace-context).
 
 ### 1. Automatic Trace ID Propagation
 
@@ -104,25 +105,26 @@ end
 
 ### 2. Background Job Propagation
 
-> **Implementation:** See [ADR-005 Section 6.2: Job Propagator](../ADR-005-tracing-context.md#62-job-propagator-sidekiqactivejob) for Sidekiq/ActiveJob integration details.
+> **Implementation:** See [ADR-005 Section 6.2: Job Propagator](../architecture/ADR-005-tracing-context.md#62-job-propagator-sidekiqactivejob) for Sidekiq/ActiveJob integration details.
 
 **Problem:** Background jobs lose trace_id context
 
 **Solution:** Automatic propagation via Sidekiq middleware
 
 ```ruby
-# lib/e11y/integrations/sidekiq.rb (built-in)
+# lib/e11y/instruments/sidekiq.rb (built-in)
+# C17 Hybrid: Job gets NEW trace_id; parent_trace_id links to enqueuing request
 module E11y
-  module Integrations
-    class SidekiqMiddleware
-      def call(worker, job, queue)
-        # Extract trace_id from job payload
-        trace_id = job['trace_id']
-        
-        # Set thread-local trace_id
-        E11y::TraceId.with_trace_id(trace_id) do
-          yield  # Execute job
-        end
+  module Instruments
+    class Sidekiq::ServerMiddleware
+      def setup_job_context(job, queue)
+        # Extract parent from job payload
+        parent_trace_id = job['e11y_parent_trace_id']
+        # Generate NEW trace_id for this job
+        E11y::Current.trace_id = generate_trace_id
+        E11y::Current.parent_trace_id = parent_trace_id
+        E11y::Current.sampled = job['e11y_sampled']  # Propagate sampling decision
+        # ...
       end
     end
   end
@@ -149,43 +151,43 @@ class OrdersController < ApplicationController
   def create
     order = Order.create!(params)
     
-    # Enqueue job (trace_id automatically passed)
+    # Enqueue job (C17: parent_trace_id + e11y_sampled propagated)
     SendOrderConfirmationJob.perform_later(order.id)
-    # → Job payload includes: { 'trace_id' => 'abc-123' }
+    # → Job payload includes: { 'e11y_parent_trace_id' => 'abc-123', 'e11y_sampled' => true }
     
     render json: order
   end
 end
 
-# In job (trace_id: abc-123 - PRESERVED!)
+# In job (C17 Hybrid: NEW trace_id xyz-789, parent_trace_id: abc-123)
 class SendOrderConfirmationJob < ApplicationJob
   def perform(order_id)
     order = Order.find(order_id)
     
-    # trace_id is automatically restored!
+    # Job gets NEW trace_id; parent_trace_id links to originating request
     Events::EmailSending.track(order_id: order.id)
-    # → trace_id = 'abc-123' (same as original request!)
+    # → trace_id = 'xyz-789', parent_trace_id = 'abc-123'
     
     UserMailer.order_confirmation(order).deliver_now
     
     Events::EmailSent.track(order_id: order.id)
-    # → trace_id = 'abc-123' (still same!)
+    # → trace_id = 'xyz-789' (same job trace)
   end
 end
 
-# Timeline in Grafana:
+# Timeline in Grafana (C17 Hybrid):
 # 10:00:00.000 [abc-123] order.created (controller)
 # 10:00:00.050 [abc-123] payment.processed (controller)
-# 10:00:00.100 [abc-123] email.sending (job, 3 seconds later)
-# 10:00:03.200 [abc-123] email.sent (job)
-# → Complete trace across HTTP request + background job!
+# 10:00:00.100 [xyz-789] email.sending (job, parent: abc-123)
+# 10:00:03.200 [xyz-789] email.sent (job)
+# → Query by parent_trace_id to link job trace to request trace
 ```
 
 ---
 
 ### 3. Cross-Service Propagation
 
-> **Implementation:** See [ADR-005 Section 6.1: HTTP Propagator](../ADR-005-tracing-context.md#61-http-propagator-outgoing-requests) for outgoing request integration (Faraday, HTTP.rb).
+> **Implementation:** See [ADR-005 Section 6.1: HTTP Propagator](../architecture/ADR-005-tracing-context.md#61-http-propagator-outgoing-requests) for outgoing request integration (Faraday, HTTP.rb).
 
 **Microservices scenario:**
 ```ruby
@@ -507,7 +509,7 @@ end
 
 ### 6. Trace-Consistent Sampling Integration
 
-> **Implementation:** See [ADR-005 Section 7: Sampling Decisions](../ADR-005-tracing-context.md#7-sampling-decisions-trace-consistent-sampling) for trace-consistent sampling architecture.
+> **Implementation:** See [ADR-005 Section 7: Sampling Decisions](../architecture/ADR-005-tracing-context.md#7-sampling-decisions-trace-consistent-sampling) for trace-consistent sampling architecture.
 
 **Critical Feature:** Sampling decisions must be consistent across trace boundaries
 

data/docs/use_cases/UC-007-pii-filtering.md

@@ -5,31 +5,20 @@
 **Setup Time:** 20-30 minutes  
 **Target Users:** All developers, Security teams, Compliance teams
 
+> **Approach:** Event-level `pii_filtering do` in event classes. Use inheritance for shared rules (e.g. `BaseUserEvent`). No global `config.pii_filter`.
+
 ---
 
 ## 📋 Overview
 
 ### Problem Statement
 
-**Current Approach (Configuration Duplication):**
+**Current Approach (Manual per-event):**
 ```ruby
-# config/application.rb
-# Rails already has PII filtering
-config.filter_parameters += [:password, :email, :ssn, :credit_card]
-
-# config/initializers/e11y.rb
-# Do we need to duplicate for E11y?
-E11y.configure do |config|
-  config.pii_filter do
-    mask_fields :password, :email, :ssn, :credit_card  # ← Duplication! 😞
-  end
-end
-
+# Each event class needs its own PII rules — duplication across similar events
 # Problems:
-# - Configuration duplication
-# - Easy to forget updating both places
-# - Inconsistency risk
-# - More maintenance burden
+# - Duplication across UserRegistered, UserLogin, PaymentCreated, etc.
+# - Easy to forget or be inconsistent
 ```
 
 ### E11y Solution
@@ -92,31 +81,25 @@ Events::UserCreated.track(
 
 ---
 
-### 2. Extended Configuration (Optional)
+### 2. Event-Level DSL + Inheritance
 
-**Add more filters beyond Rails:**
+**Define per-event; use inheritance for shared rules:**
 ```ruby
-# config/initializers/e11y.rb
-E11y.configure do |config|
-  config.pii_filter do
-    # 1. USE RAILS FILTERS (default: true)
-    use_rails_filter_parameters true
-    
-    # 2. ADD MORE FIELDS (Rails-compatible syntax)
-    filter_parameters :api_key, :token, :auth_token, :secret_key
-    
-    # 3. REGEX FILTERS (like Rails)
-    filter_parameters /token/i       # Matches: auth_token, api_token, etc.
-    filter_parameters /secret/i      # Matches: client_secret, api_secret, etc.
-    
-    # 4. WHITELIST (don't filter these, even if in Rails.filter_parameters)
-    allow_parameters :user_id, :order_id, :transaction_id
-    
-    # 5. CUSTOM REPLACEMENT (default: '[FILTERED]')
-    replacement '[REDACTED]'
-    
-    # 6. KEEP PARTIAL DATA (for debugging)
-    keep_partial_data true  # 'em***@ex***' instead of '[FILTERED]'
+# Base class — common rules for all user events
+class BaseUserEvent < E11y::Event::Base
+  contains_pii true
+  pii_filtering do
+    masks   :password, :api_key, :token
+    hashes  :email
+    partials :phone
+    allows  :user_id, :order_id
+  end
+end
+
+# Child — inherits + adds payment-specific fields
+class Events::PaymentCreated < BaseUserEvent
+  pii_filtering do
+    masks :card_number, :cvv
   end
 end
 ```
@@ -125,42 +108,7 @@ end
 
 ### 3. Pattern-Based Filtering (Beyond Rails)
 
-**Advanced regex patterns for content scanning:**
-```ruby
-E11y.configure do |config|
-  config.pii_filter do
-    # EMAIL ADDRESSES (scan content, not just keys)
-    filter_pattern /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i,
-                   replacement: '[EMAIL]'
-    
-    # CREDIT CARDS
-    filter_pattern /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/,
-                   replacement: '[CARD]'
-    
-    # SOCIAL SECURITY NUMBERS
-    filter_pattern /\b\d{3}-\d{2}-\d{4}\b/,
-                   replacement: '[SSN]'
-    
-    # PHONE NUMBERS (US/International)
-    filter_pattern /\b(\+\d{1,2}\s?)?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}\b/,
-                   replacement: '[PHONE]'
-    
-    # IP ADDRESSES
-    filter_pattern /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/,
-                   replacement: '[IP]'
-    
-    # API KEYS (common formats)
-    filter_pattern /[A-Za-z0-9_]{32,}/,  # Long alphanumeric strings
-                   replacement: '[API_KEY]'
-  end
-end
-
-# Usage:
-Events::EmailSent.track(
-  subject: 'Hello user@example.com!',  # → 'Hello [EMAIL]!'
-  body: 'Your card 4111-1111-1111-1111 was charged'  # → 'Your card [CARD] was charged'
-)
-```
+**:explicit_pii events** (`contains_pii true`) apply `E11y::PII::Patterns::VALUE_PATTERNS` to string values (email, SSN, credit card regexes). Field-level strategies (masks, hashes, partials) are defined in `pii_filtering do`. Per-adapter overrides use `exclude_adapters`; PIIFilter produces `payload_rewrites`, Routing merges per adapter.
 
 ---
 
@@ -493,7 +441,7 @@ end
 
 ## 🔐 Explicit PII Declaration
 
-> **Implementation:** See [ADR-006 Section 3.0.3: Explicit PII Declaration](../ADR-006-security-compliance.md#303-explicit-pii-declaration) for detailed architecture.
+> **Implementation:** See [ADR-006 Section 3.0.3: Explicit PII Declaration](../architecture/ADR-006-security-compliance.md#303-explicit-pii-declaration) for detailed architecture.
 
 **Critical Design Principle:** Event classes MUST explicitly declare whether they contain PII. This enables E11y to apply the appropriate filtering tier (see Performance Tiers below) and allows linter validation.
 
@@ -510,7 +458,7 @@ end
 
 ### Declaration Syntax: `contains_pii`
 
-**Option 1: No PII (Tier 1 - Skip Filtering)**
+**Option 1: No PII (:no_pii — Skip Filtering)**
 
 ```ruby
 class Events::HealthCheck < E11y::Event::Base
@@ -523,13 +471,13 @@ class Events::HealthCheck < E11y::Event::Base
   contains_pii false
   
   # Result:
-  # - Tier 1 filtering (0ms overhead)
+  # - :no_pii filtering (0ms overhead)
   # - All fields logged as-is
   # - No pattern scanning
 end
 ```
 
-**Option 2: Default (Tier 2 - Rails Filters Only)**
+**Option 2: Default (:rails_filters — Rails Filters Only)**
 
 ```ruby
 class Events::OrderCreated < E11y::Event::Base
@@ -539,12 +487,12 @@ class Events::OrderCreated < E11y::Event::Base
     optional(:api_key).filled(:string)  # Rails will filter this
   end
   
-  # No declaration → Tier 2 (Rails filters applied)
+  # No declaration → :rails_filters (Rails filters applied)
   # Keys like :password, :token, :api_key automatically filtered
 end
 ```
 
-**Option 3: Explicit PII (Tier 3 - Deep Filtering)**
+**Option 3: Explicit PII (:explicit_pii — Deep Filtering)**
 
 ```ruby
 class Events::UserRegistered < E11y::Event::Base
@@ -751,7 +699,7 @@ end
 
 ### Default Behavior (No Declaration)
 
-If `contains_pii` is not specified, E11y defaults to **Tier 2** (Rails filters only):
+If `contains_pii` is not specified, E11y defaults to **:rails_filters** (Rails filters only):
 
 ```ruby
 class Events::OrderPaid < E11y::Event::Base
@@ -761,7 +709,7 @@ class Events::OrderPaid < E11y::Event::Base
   end
   
   # No contains_pii declaration
-  # → Tier 2: Rails filters applied automatically
+  # → :rails_filters: Rails filters applied automatically
   # → Keys like :password, :token, :api_key filtered
   # → No linter validation
 end
@@ -970,7 +918,7 @@ end
 
 ## ⚡ DSL Shortcuts (Rails-Style)
 
-> **Implementation:** See [ADR-006 Section 3.4.4: Configuration API (Rails-Style DSL)](../ADR-006-security-compliance.md#344-configuration-api-rails-style-dsl) for detailed architecture.
+> **Implementation:** See [ADR-006 Section 3.4.4: Configuration API (Rails-Style DSL)](../architecture/ADR-006-security-compliance.md#344-configuration-api-rails-style-dsl) for detailed architecture.
 
 E11y provides **Rails-style DSL shortcuts** to simplify PII declarations. Instead of verbose `field` blocks, use one-liner shortcuts like `masks`, `hashes`, `skips` – similar to Rails validations.
 
@@ -1398,7 +1346,7 @@ masks :password, :token
 
 ## 🔍 Linter Enforcement
 
-> **Implementation:** See [ADR-006 Section 3.0.5: PII Declaration Linter](../ADR-006-security-compliance.md#305-pii-declaration-linter) for detailed architecture.
+> **Implementation:** See [ADR-006 Section 3.0.5: PII Declaration Linter](../architecture/ADR-006-security-compliance.md#305-pii-declaration-linter) for detailed architecture.
 
 E11y includes a **PII Declaration Linter** that validates PII handling at boot time and in CI. This catches missing declarations, typos, and incomplete coverage BEFORE code reaches production.
 
@@ -1770,7 +1718,7 @@ end
 
 ## ⚡ Performance Tiers
 
-> **Implementation:** See [ADR-006 Section 3.0: PII Filtering Strategy](../ADR-006-security-compliance.md#30-pii-filtering-strategy) for detailed architecture.
+> **Implementation:** See [ADR-006 Section 3.0: PII Filtering Strategy](../architecture/ADR-006-security-compliance.md#30-pii-filtering-strategy) for detailed architecture.
 
 E11y uses a **3-tier filtering strategy** to balance security and performance. Filtering ALL events by default would create massive overhead (1M events × 0.2ms = 200 seconds CPU/day). Instead, events are categorized into 3 tiers based on PII content.