e11y 0.2.0 → 1.1.0

data/docs/{ADR-002-metrics-yabeda.md → architecture/ADR-002-metrics-yabeda.md}

@@ -2,7 +2,7 @@
 
 **Status:** Implemented  
 **Date:** January 12, 2026 (Updated: January 20, 2026)  
-**Covers:** UC-003 (Pattern-Based Metrics), UC-013 (High Cardinality Protection)  
+**Covers:** UC-003 (Event Metrics), UC-013 (High Cardinality Protection)  
 **Depends On:** ADR-001 (Core Architecture)
 
 **Implementation Notes:** Refactored to "Rails Way" architecture (January 20, 2026) - see [IMPLEMENTATION_NOTES.md](./IMPLEMENTATION_NOTES.md#2026-01-20-metrics-architecture-refactoring---rails-way-)
@@ -13,14 +13,13 @@
 
 1. [Context & Problem](#1-context--problem)
 2. [Architecture Overview](#2-architecture-overview)
-3. [Pattern-Based Metrics](#3-pattern-based-metrics)
+3. [Event Metrics](#3-event-metrics)
 4. [Cardinality Protection](#4-cardinality-protection)
-   - 4.1. [Four-Layer Defense](#41-four-layer-defense)
+   - 4.1. [Three-Layer Defense](#41-three-layer-defense)
    - 4.2. [Layer 1: Universal Denylist](#42-layer-1-universal-denylist)
-   - 4.3. [Layer 2: Safe Allowlist](#43-layer-2-safe-allowlist)
-   - 4.4. [Layer 3: Per-Metric Limits](#44-layer-3-per-metric-cardinality-limits)
-   - 4.5. [Layer 4: Dynamic Actions](#45-layer-4-dynamic-actions)
-   - 4.6. [Relabeling Rules](#46-relabeling-rules)
+   - 4.3. [Layer 2: Per-Metric Limits](#43-layer-2-per-metric-cardinality-limits)
+   - 4.4. [Layer 3: Dynamic Actions](#44-layer-3-dynamic-actions)
+   - 4.5. [Relabeling Rules](#45-relabeling-rules)
 5. [Yabeda Integration](#5-yabeda-integration)
 6. [Self-Monitoring](#6-self-monitoring)
 7. [Configuration](#7-configuration)
@@ -142,7 +141,7 @@ end
 # Adapter automatically:
 # 1. Finds matching metrics from Registry
 # 2. Extracts labels from event data
-# 3. Applies 3-layer cardinality protection
+# 3. Applies 3-layer cardinality protection (denylist, per-metric limits, dynamic actions)
 # 4. Updates Yabeda metrics
 ```
 
@@ -178,21 +177,7 @@ end
 
 ### 0.5. Global Metrics via Registry
 
-**Pattern-based metrics for multiple events:**
-
-```ruby
-# config/initializers/e11y.rb
-E11y.configure do |config|
-  # Global metric for all order.* events
-  E11y::Metrics::Registry.instance.register(
-    type: :counter,
-    pattern: 'order.*',  # Matches order.created, order.paid, etc.
-    name: :orders_total,
-    tags: [:currency, :status],
-    source: 'config/initializers/e11y.rb'
-  )
-end
-```
+**Event-level metrics** — each event class defines its own metrics via `metrics do ... end` DSL. The Registry validates and registers them at boot time.
 
 ### 0.6. Key Benefits
 
@@ -236,8 +221,8 @@ end
 > **⚠️ NOTE (C03 Resolution):** Yabeda is the **default metrics backend** for E11y. OpenTelemetry metrics are **optional** (see ADR-007). Choose ONE backend to avoid double overhead. See [CONFLICT-ANALYSIS.md C03](../researches/CONFLICT-ANALYSIS.md#c03-dual-metrics-collection-overhead) for details.
 
 **Primary Goals:**
-- ✅ Auto-create metrics from events (pattern-based)
-- ✅ Prevent cardinality explosions (4-layer defense)
+- ✅ Auto-create metrics from events (event-level DSL)
+- ✅ Prevent cardinality explosions (3-layer defense)
 - ✅ Zero manual metric definitions
 - ✅ Prometheus-friendly
 - ✅ Cost-effective (<10k time series per metric)
@@ -308,7 +293,7 @@ graph TB
     subgraph "Protection (3-Layer)"
         L1[Layer 1: Denylist]
         L2[Layer 2: Per-Metric Limits]
-        L3[Layer 3: Monitoring]
+        L3[Layer 3: Dynamic Actions]
     end
     
     EventClass -->|defines| MetricsDSL
@@ -355,8 +340,7 @@ sequenceDiagram
     loop For each metric
         Middleware->>Protection: extract_labels(event_data)
         Protection->>Protection: Check denylist (order_id? ❌)
-        Protection->>Protection: Check allowlist (status? ✅)
-        Protection->>Protection: Check cardinality (3 unique values ✅)
+        Protection->>Protection: Check cardinality (status: 3 unique values ✅)
         Protection-->>Middleware: safe_labels: {status: 'paid'}
         
         Middleware->>Yabeda: counter.increment(safe_labels)
@@ -370,7 +354,7 @@ sequenceDiagram
 
 ---
 
-## 3. Pattern-Based Metrics
+## 3. Event Metrics
 
 ### 3.1. Pattern Matching
 
@@ -449,30 +433,13 @@ graph TB
 
 **Configuration:**
 
+
 ```ruby
-E11y.configure do |config|
-  config.metrics do
-    # Counter: count events
-    counter pattern: 'order.*',
-            name: 'orders_total',
-            comment: 'Total orders by status',
-            tags: [:status],  # ← Extract from payload
-            unit: :count
-    
-    # Histogram: measure values
-    histogram pattern: 'order.paid',
-              name: 'order_amount',
-              comment: 'Order payment amounts',
-              tags: [:payment_method],
-              unit: :dollars,
-              buckets: [10, 50, 100, 500, 1000, 5000]
-    
-    # Gauge: current value
-    gauge pattern: 'buffer.*',
-          name: 'buffer_size',
-          comment: 'Current buffer size',
-          tags: [:buffer_type],
-          unit: :events
+# Event-level metrics (implemented)
+class Events::OrderPaid < E11y::Event::Base
+  metrics do
+    counter :orders_total, tags: [:status]
+    histogram :order_amount, value: :amount, tags: [:payment_method], buckets: [10, 50, 100, 500]
   end
 end
 ```
@@ -540,7 +507,7 @@ Layers are applied **sequentially** (not simultaneously):
 
 1. **Layer 1 (Universal Denylist):** If label in denylist → DROP, stop processing
 2. **Layer 2 (Per-Metric Limits):** Track unique values per label, drop if exceeded
-3. **Layer 3 (Monitoring):** Log warnings when limits exceeded
+3. **Layer 3 (Dynamic Actions):** Configurable action on overflow (drop, alert, relabel)
 
 **Example Flow:**
 
@@ -550,13 +517,12 @@ Label: user_id
 
 Label: status
 → Layer 1: in FORBIDDEN_LABELS? ❌ No → continue
-→ Layer 2: in SAFE_LABELS? ✅ Yes → KEEP ✅ (skip Layer 3-4)
+→ Layer 2: cardinality < limit? ✅ Yes (3 values) → KEEP ✅
 
 Label: custom_field
 → Layer 1: in FORBIDDEN_LABELS? ❌ No → continue
-→ Layer 2: in SAFE_LABELS? ❌ No → continue
-→ Layer 3: cardinality < limit? ❌ No (150 > 100) → continue
-→ Layer 4: action=drop → DROP ❌
+→ Layer 2: cardinality < limit? ❌ No (150 > 100) → continue
+→ Layer 3: action=drop → DROP ❌
 ```
 
 ```mermaid
@@ -564,16 +530,13 @@ graph TB
     Input[Event Labels] --> L1{Layer 1<br/>Denylist}
     
     L1 -->|In denylist| Drop1[❌ Drop Label]
-    L1 -->|Not in denylist| L2{Layer 2<br/>Allowlist}
-    
-    L2 -->|In allowlist| Keep[✅ Keep Label]
-    L2 -->|Not in allowlist| L3{Layer 3<br/>Cardinality Limit}
+    L1 -->|Not in denylist| L2{Layer 2<br/>Per-Metric Limit}
     
-    L3 -->|Under limit| Keep
-    L3 -->|Over limit| L4{Layer 4<br/>Dynamic Action}
+    L2 -->|Under limit| Keep[✅ Keep Label]
+    L2 -->|Over limit| L3{Layer 3<br/>Dynamic Action}
     
-    L4 -->|drop| Drop2[❌ Drop Label]
-    L4 -->|alert| Alert[🚨 Alert + Drop]
+    L3 -->|drop| Drop2[❌ Drop Label]
+    L3 -->|alert| Alert[🚨 Alert + Drop]
     
     Drop1 --> Log1[Log: denylist_hit]
     Drop2 --> Log2[Log: cardinality_exceeded]
@@ -582,9 +545,8 @@ graph TB
     Keep --> Metric[Export to Yabeda]
     
     style L1 fill:#f8d7da
-    style L2 fill:#d4edda
-    style L3 fill:#fff3cd
-    style L4 fill:#d1ecf1
+    style L2 fill:#fff3cd
+    style L3 fill:#d1ecf1
     style Drop1 fill:#f8d7da
     style Drop2 fill:#f8d7da
     style Keep fill:#d4edda
@@ -673,53 +635,7 @@ graph LR
     style File fill:#d4edda
 ```
 
-### 4.3. Layer 2: Safe Allowlist
-
-**Decision:** Pre-approved low-cardinality labels.
-
-```ruby
-module E11y
-  module Metrics
-    class CardinalityProtection
-      # Safe labels (low cardinality, always allowed)
-      SAFE_LABELS = [
-        # Status/state
-        :status, :state, :result, :outcome,
-        
-        # Types/categories
-        :type, :kind, :category, :class_name,
-        
-        # Methods/operations
-        :method, :action, :operation, :command,
-        
-        # Environments
-        :env, :environment, :region, :zone, :datacenter,
-        
-        # Services
-        :service, :component, :adapter, :backend,
-        
-        # Severities
-        :severity, :level, :priority,
-        
-        # HTTP
-        :http_method, :http_status, :http_status_class,  # (200 → '2xx')
-        
-        # Protocols
-        :protocol, :version,
-        
-        # Success/failure
-        :success, :error_type, :error_class
-      ].freeze
-      
-      def in_allowlist?(label_name)
-        SAFE_LABELS.include?(label_name.to_sym)
-      end
-    end
-  end
-end
-```
-
-### 4.4. Layer 3: Per-Metric Cardinality Limits
+### 4.3. Layer 2: Per-Metric Cardinality Limits
 
 **Decision:** Track unique values per label, enforce limits.
 
@@ -783,7 +699,7 @@ tracker.check_and_track('orders_total', :status, 'cancelled')  # ❌ false (limi
 tracker.check_and_track('orders_total', :status, 'paid')  # ✅ true (seen before)
 ```
 
-### 4.5. Layer 4: Dynamic Actions
+### 4.4. Layer 3: Dynamic Actions
 
 **Decision:** Configurable actions when limits exceeded.
 
@@ -822,8 +738,8 @@ Events::ApiCall.track(
   customer_id: 'cust_12345'  # ← 101st unique value, exceeds limit
 )
 
-# Layer 3: cardinality exceeded (100 limit)
-# Layer 4: action=drop → customer_id dropped
+# Layer 2: cardinality exceeded (100 limit)
+# Layer 3: action=drop → customer_id dropped
 
 # Result metric:
 # api_calls_total{endpoint="/api/users"} 1
@@ -863,7 +779,7 @@ graph TB
 
 **Note:** For v1.0, we keep it simple with just **drop** and **alert**. Advanced strategies (hash bucketing, aggregation) can be added in v1.1+ if needed.
 
-### 4.6. Relabeling Rules
+### 4.5. Relabeling Rules
 
 **Decision:** Transform high-cardinality labels to low-cardinality.
 
@@ -937,21 +853,16 @@ end
 
 ### 5.2. Metric Registration
 
+
 ```ruby
-# Auto-create Yabeda metrics from config
-E11y.configure do |config|
-  config.metrics do
-    counter pattern: 'order.*',
-            name: :orders_total,
-            comment: 'Total orders',
-            tags: [:status]
+# Event-level metrics (implemented)
+class Events::OrderCreated < E11y::Event::Base
+  metrics do
+    counter :orders_total, tags: [:status]
   end
 end
 
-# Internally creates:
-Yabeda.e11y.counter :orders_total,
-                    tags: [:status],
-                    comment: 'Total orders'
+# Yabeda adapter auto-registers from Registry when events are loaded
 ```
 
 ### 5.3. Metric Updates
@@ -1052,97 +963,17 @@ end
 ```ruby
 # config/initializers/e11y.rb
 E11y.configure do |config|
-  config.metrics do
-    # Enable metrics
-    enabled true
-    
-    # Yabeda integration
-    yabeda_integration true
-    
-    # ===== Pattern-Based Metrics =====
-    
-    # Counter: count all orders
-    counter pattern: 'order.*',
-            name: :orders_total,
-            comment: 'Total orders by status and payment method',
-            tags: [:status, :payment_method],
-            unit: :count
-    
-    # Histogram: order amounts
-    histogram pattern: 'order.paid',
-              name: :order_amount,
-              comment: 'Order payment amounts',
-              tags: [:payment_method, :currency],
-              value_field: :amount,  # Extract from payload
-              unit: :dollars,
-              buckets: [10, 50, 100, 500, 1000, 5000, 10000]
-    
-    # Histogram: API response times
-    histogram pattern: 'api.*',
-              name: :api_duration_seconds,
-              comment: 'API call durations',
-              tags: [:endpoint, :http_status_class],
-              value_field: :duration,
-              unit: :seconds,
-              buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5]
-    
-    # ===== Cardinality Protection =====
-    
-    cardinality_protection do
-      # Default limit per label
-      default_cardinality_limit 100
-      
-      # Per-metric limits
-      per_metric do
-        metric :orders_total, label: :status, limit: 10
-        metric :orders_total, label: :payment_method, limit: 20
-        metric :api_duration_seconds, label: :endpoint, limit: 500
-      end
-      
-      # Action on excess
-      action_on_excess :drop  # :drop or :alert
-      
-      # Denylist (in addition to universal)
-      forbidden_labels [
-        :customer_id,
-        :internal_ref
-      ]
-      
-      # Allowlist (in addition to safe list)
-      allowed_labels [
-        :subscription_tier,
-        :user_role
-      ]
-      
-      # Relabeling rules
-      relabel :http_status do |value|
-        "#{value.to_i / 100}xx"
-      end
-      
-      relabel :path do |value|
-        value.gsub(/\/\d+/, '/:id')
-      end
-      
-      # Monitoring
-      monitoring do
-        alert_on_new_label true
-        alert_threshold 80  # Alert at 80% of limit
-        
-        on_alert do |metric_name, label_name, cardinality, limit|
-          Rails.logger.warn "Cardinality alert: #{metric_name}.#{label_name} = #{cardinality}/#{limit}"
-        end
-      end
-    end
-    
-    # ===== Advanced Features =====
-    
-    # Exemplars (sample trace IDs for metric values)
-    exemplars do
-      enabled true
-      max_per_bucket 1  # 1 trace_id per histogram bucket
-    end
-  end
+  config.adapters[:metrics] = E11y::Adapters::Yabeda.new
 end
+
+# Define metrics in event classes:
+# class Events::OrderPaid < E11y::Event::Base
+#   metrics do
+#     counter :orders_total, tags: [:status, :payment_method]
+#     histogram :order_amount, value: :amount, tags: [:payment_method, :currency],
+#               buckets: [10, 50, 100, 500, 1000, 5000]
+#   end
+# end
 ```
 
 ---
@@ -1238,7 +1069,7 @@ RSpec.describe E11y::Metrics::CardinalityProtection do
     end
   end
   
-  describe 'Layer 3: Cardinality Limits' do
+  describe 'Layer 2: Cardinality Limits' do
     it 'enforces per-metric limits' do
       protection = CardinalityProtection.new(
         limits: { orders_total: { status: 3 } }
@@ -1269,7 +1100,7 @@ end
 |----------|-----|-----|-----------|
 | **Auto-metrics** | Zero boilerplate | Less control | DX > control |
 | **Pattern matching** | Flexible | Slower than exact | Flexibility matters |
-| **4-layer defense** | Robust | Complex | Safety critical |
+| **3-layer defense** | Robust | Complex | Safety critical |
 | **Hash bucketing** | Preserves some signal | Loss of precision | Better than drop |
 | **Yabeda dependency** | Battle-tested | External dep | Standard in Ruby |
 
@@ -1310,7 +1141,7 @@ Loki/Sentry/File:
 
 ---
 
-### Q2: Are Layers 1-4 applied simultaneously or sequentially?
+### Q2: Are Layers 1–3 applied simultaneously or sequentially?
 
 **A: Sequentially (waterfall), not simultaneously.**
 
@@ -1321,16 +1152,12 @@ Processing order:
    ↓ If in denylist → DROP, stop
    ↓ If not in denylist → continue to Layer 2
 
-2. Layer 2 (Allowlist)
-   ↓ If in allowlist → KEEP, skip Layer 3-4
-   ↓ If not in allowlist → continue to Layer 3
-
-3. Layer 3 (Cardinality Limit)
+2. Layer 2 (Per-Metric Limit)
    ↓ If under limit → KEEP, stop
-   ↓ If over limit → continue to Layer 4
+   ↓ If over limit → continue to Layer 3
 
-4. Layer 4 (Dynamic Action)
-   ↓ Apply configured action: hash/drop/aggregate/alert
+3. Layer 3 (Dynamic Action)
+   ↓ Apply configured action: drop/alert/relabel
 ```
 
 **Example:**
@@ -1343,15 +1170,14 @@ Processing order:
 
 # status:
 #   Layer 1: not in FORBIDDEN_LABELS → continue
-#   Layer 2: in SAFE_LABELS → ✅ KEEP (skip Layer 3-4)
+#   Layer 2: cardinality under limit → ✅ KEEP
 
 # tier:
 #   Layer 1: not in FORBIDDEN_LABELS → continue
-#   Layer 2: not in SAFE_LABELS → continue
-#   Layer 3: cardinality = 150 > limit (100) → continue
-#   Layer 4: action=hash → ✅ KEEP as "bucket_7"
+#   Layer 2: cardinality = 150 > limit (100) → continue
+#   Layer 3: action=drop → ❌ DROP
 
-# Result: { status: 'paid', tier_bucket: 'bucket_7' }
+# Result: { status: 'paid' }
 ```
 
 ---