e11y 0.2.0 → 1.1.0

data/docs/{00-ICP-AND-TIMELINE.md → prd/00-ICP-AND-TIMELINE.md}

@@ -39,7 +39,7 @@
 - High cardinality costs (Datadog, New Relic bills exploding)
 
 **What They Need:**
-- ✅ Pattern-based metrics (reduce boilerplate)
+- ✅ Event-level metrics DSL (reduce boilerplate)
 - ✅ Cardinality protection (prevent cost explosions)
 - ✅ Multi-adapter support (integrate with existing stack)
 - ✅ Team-wide conventions (event schemas, PII filtering)
@@ -135,10 +135,10 @@
 
 ### Phase 2: Yabeda Integration (Weeks 9-12)
 **Target:** April 2025
-**Goal:** Pattern-based metrics automation
+**Goal:** Event-level metrics automation
 
-**Week 9-10: Pattern Engine**
-- [ ] Pattern matching (`*`, `order.*`, `*.paid`)
+**Week 9-10: Metrics DSL**
+- [ ] Event-level `metrics do ... end` DSL
 - [ ] Label extraction from events
 - [ ] Counter metrics
 - [ ] Histogram metrics (with buckets)
@@ -261,7 +261,7 @@
 **Focus:** Feature-complete release candidate
 
 **New Features:**
-- ✅ Pattern-based metrics (Yabeda)
+- ✅ Event-level metrics (Yabeda)
 - ✅ Cardinality protection
 - ✅ SLO tracking (zero-config)
 - ✅ OpenTelemetry integration
@@ -424,7 +424,7 @@
 - ✅ Rails-first design (vs OTel's language-agnostic complexity)
 - ✅ Zero-config SLO tracking (unique feature)
 - ✅ Request-scoped debug buffering (unique feature)
-- ✅ Pattern-based metrics (less boilerplate)
+- ✅ Event-level metrics DSL (less boilerplate)
 - ✅ Cost optimization built-in (vs expensive SaaS)
 
 ---

data/docs/{01-SCALE-REQUIREMENTS.md → prd/01-SCALE-REQUIREMENTS.md}

@@ -66,11 +66,11 @@ E11y.configure do |config|
     worker_threads 2         # Multiple workers
   end
   
-  # Adaptive sampling для cost control
+  # Adaptive sampling for cost control
   config.sampling do
     strategy :adaptive
     target_samples_per_second 200  # Cap at 200/sec
-    min_rate 0.1  # Minimum 10% даже при высокой нагрузке
+    min_rate 0.1  # Minimum 10% even under high load
   end
 end
 ```
@@ -112,13 +112,13 @@ E11y.configure do |config|
     worker_threads 4         # Multiple workers
   end
   
-  # Агрессивный sampling
+  # Aggressive sampling
   config.sampling do
     strategy :adaptive
     target_samples_per_second 1_000  # Cap at 1k/sec
-    min_rate 0.01  # 1% минимум
+    min_rate 0.01  # 1% minimum
     
-    # Tail-based sampling для критичных событий
+    # Tail-based sampling for critical events
     tail do
       enabled true
       sample_if do |events|
@@ -481,7 +481,7 @@ E11y.configure do |config|
     target_samples_per_second 1_000
     min_rate 0.01  # 1% minimum
     
-    # Tail-based sampling для критичных событий
+    # Tail-based sampling for critical events
     tail do
       enabled true
       sample_if do |events|

data/docs/prd/01-overview-vision.md

@@ -9,15 +9,15 @@
 
 ## 📋 Executive Summary
 
-**E11y** (easy telemetry) - production-ready Ruby gem для структурированных бизнес-событий с уникальными killer features:
+**E11y** (easy telemetry) - production-ready Ruby gem for structured business events with unique killer features:
 
-1. **Request-scoped debug buffering** - debug events только при ошибках (89% reduction)
-2. **Pattern-based metrics** - автоматические метрики без boilerplate
-3. **Zero-config SLO tracking** - built-in monitoring одной строкой конфига
+1. **Request-scoped debug buffering** - debug events only on errors (89% reduction)
+2. **Event-level metrics DSL** - automatic metrics without boilerplate
+3. **Zero-config SLO tracking** - built-in monitoring with a single config line
 
 **Target Market:** Ruby/Rails teams (5-100 engineers)  
-**Problem:** Observability сложна, дорога и перегружена шумом  
-**Solution:** Простой, Rails-first gem с production-ready defaults
+**Problem:** Observability is complex, expensive, and overloaded with noise  
+**Solution:** Simple, Rails-first gem with production-ready defaults
 
 ---
 
@@ -160,14 +160,19 @@ E11y.configure { |config| config.slo_tracking = true }
 
 #### 3. Automatic Metrics
 
-**Pattern-based metrics:**
+**Event-level metrics DSL:**
 ```ruby
-# Define event once
-Events::OrderPaid.track(order_id: '123', amount: 99, currency: 'USD')
+# Define event once with metrics
+class Events::OrderPaid < E11y::Event::Base
+  schema { required(:order_id).filled(:string); required(:amount).filled(:float); optional(:currency).maybe(:string) }
+  metrics do
+    counter :orders_paid_total, tags: [:currency]
+    histogram :order_amount, value: :amount, tags: [:currency]
+  end
+end
 
-# Get metrics automatically (configured via patterns)
-# - orders.paid.total{currency="USD"} = 1
-# - orders.paid.amount{currency="USD"} = 99
+Events::OrderPaid.track(order_id: '123', amount: 99, currency: 'USD')
+# → orders_paid_total{currency="USD"} = 1, order_amount{currency="USD"} = 99
 ```
 
 **Result:** No boilerplate, no duplication, consistent.
@@ -243,7 +248,7 @@ end
 | **Setup complexity** | High (5+ pages) | Low (1 line) |
 | **Rails integration** | Manual | Automatic |
 | **Request-scoped buffering** | ❌ | ✅ |
-| **Pattern-based metrics** | ❌ | ✅ |
+| **Event-level metrics DSL** | ❌ | ✅ |
 | **SLO tracking** | Manual setup | One-line config |
 | **Target audience** | Polyglot teams | Rails teams |
 
@@ -363,7 +368,7 @@ end
 ✅ <1ms p99 latency
 
 **v1.0 (Phase 5):**
-✅ Pattern-based metrics (Yabeda)  
+✅ Event-level metrics (Yabeda)  
 ✅ Zero-config SLO tracking  
 ✅ OpenTelemetry integration  
 ✅ Cardinality protection  

data/docs/use_cases/README.md

@@ -1,18 +1,18 @@
 # E11y Use Cases Documentation
 
-Эта папка содержит детальные use cases для различных сценариев использования E11y gem.
+This folder contains detailed use cases for various E11y gem usage scenarios.
 
-## 📁 Структура
+## 📁 Structure
 
 ### Core Use Cases
-- **[UC-001: Request-Scoped Debug Buffering](./UC-001-request-scoped-debug-buffering.md)** - Killer feature: debug events только при ошибках
-- **[UC-002: Business Event Tracking](./UC-002-business-event-tracking.md)** - Структурированные бизнес-события
-- **[UC-003: Pattern-Based Metrics](./UC-003-pattern-based-metrics.md)** - Автоматические метрики из событий
+- **[UC-001: Request-Scoped Debug Buffering](./UC-001-request-scoped-debug-buffering.md)** - Killer feature: debug events only on errors
+- **[UC-002: Business Event Tracking](./UC-002-business-event-tracking.md)** - Structured business events
+- **[UC-003: Event Metrics](./UC-003-event-metrics.md)** - Metrics in event classes
 - **[UC-004: Zero-Config SLO Tracking](./UC-004-zero-config-slo-tracking.md)** - Built-in SLO monitoring
 
 ### Integration Use Cases
-- **[UC-005: Sentry Integration](./UC-005-sentry-integration.md)** - Error tracking с автоматическими breadcrumbs
-- **[UC-006: Trace Context Management](./UC-006-trace-context-management.md)** - Автоматическая корреляция через trace_id
+- **[UC-005: Sentry Integration](./UC-005-sentry-integration.md)** - Error tracking with automatic breadcrumbs
+- **[UC-006: Trace Context Management](./UC-006-trace-context-management.md)** - Automatic correlation via trace_id
 - **[UC-007: PII Filtering](./UC-007-pii-filtering.md)** - Rails-compatible PII filtering
 - **[UC-008: OpenTelemetry Integration](./UC-008-opentelemetry-integration.md)** - OTel compatibility
 - **[UC-009: Multi-Service Tracing](./UC-009-multi-service-tracing.md)** - Distributed tracing
@@ -34,7 +34,7 @@
 - **[UC-018: Testing Events](./UC-018-testing-events.md)** - Test strategies
 - **[UC-020: Event Versioning](./UC-020-event-versioning.md)** - Schema evolution & backward compatibility
 - **[UC-021: Error Handling & DLQ](./UC-021-error-handling-retry-dlq.md)** - Retry policy & dead letter queue
-- **[UC-022: Event Registry](./UC-022-event-registry.md)** - Event introspection & discovery
+- **[UC-022: Event Registry](./UC-022-event-registry.md)** - Event discovery (find, event_classes, where)
 
 ## 🎯 Use Case Categories
 
@@ -42,15 +42,15 @@
 
 **Ruby/Rails Developers:**
 - UC-002 (Business Event Tracking)
-- UC-014 (Rails Logger Migration)
-- UC-015 (Local Development)
-- UC-016 (Testing Events)
+- UC-016 (Rails Logger Migration)
+- UC-017 (Local Development)
+- UC-018 (Testing Events)
 
 **DevOps/SRE Engineers:**
 - UC-001 (Request-Scoped Debug Buffering)
 - UC-004 (Zero-Config SLO Tracking)
 - UC-008 (OpenTelemetry Integration)
-- UC-011 (Adaptive Sampling)
+- UC-014 (Adaptive Sampling)
 
 **Security/Compliance Teams:**
 - UC-007 (PII Filtering)
@@ -60,7 +60,7 @@
 **Engineering Managers/CTOs:**
 - UC-015 (Cost Optimization)
 - UC-013 (High Cardinality Protection)
-- UC-003 (Pattern-Based Metrics)
+- UC-003 (Event Metrics)
 
 ### By Complexity
 
@@ -72,7 +72,7 @@
 
 **Intermediate (15-60 min setup):**
 - UC-001 (Request-Scoped Debug Buffering)
-- UC-003 (Pattern-Based Metrics)
+- UC-003 (Event Metrics)
 - UC-004 (Zero-Config SLO Tracking)
 - UC-006 (Trace Context Management)
 - UC-007 (PII Filtering)
@@ -89,9 +89,9 @@
 
 ### For New Users
 Start with:
-1. UC-002 (Business Event Tracking) - понять основы
-2. UC-015 (Local Development) - настроить локально
-3. UC-004 (Zero-Config SLO Tracking) - получить метрики
+1. UC-002 (Business Event Tracking) - learn the basics
+2. UC-017 (Local Development) - set up locally
+3. UC-004 (Zero-Config SLO Tracking) - get metrics
 
 ### For Production Deployment
 Review:
@@ -103,15 +103,14 @@ Review:
 ### For Migration from Existing Tools
 See:
 1. UC-016 (Rails Logger Migration)
-2. UC-008 (OpenTelemetry Integration) - если уже используете OTel
-3. UC-009 (Multi-Service Tracing) - если microservices
+2. UC-008 (OpenTelemetry Integration) - if you already use OTel
+3. UC-009 (Multi-Service Tracing) - for microservices
 
 ## 🔗 Related Documentation
 
-- **[Quick Start Guide](../E11Y-QUICK-START.md)** - 5-minute setup
-- **[API Reference](../api/README.md)** - Detailed API docs
-- **[Architecture Overview](../architecture/README.md)** - System design
-- **[Configuration Guide](../configuration/README.md)** - All config options
+- **[Quick Start Guide](../QUICK-START.md)** - 5-minute setup
+- **[Architecture Overview](../architecture/ADR-INDEX.md)** - System design
+- **[Configuration Guide](../CONFIGURATION.md)** - All config options
 
 ---
 

data/docs/use_cases/UC-001-request-scoped-debug-buffering.md

@@ -234,7 +234,7 @@ end
 > config.pipeline.use RoutingMiddleware         # 6. Buffer routing (LAST!)
 > ```
 > 
-> **See:** [ADR-001 Section 4.1: Middleware Execution Order](../ADR-001-architecture.md#41-middleware-execution-order-critical) and [ADR-015: Middleware Order Reference](../ADR-015-middleware-order.md) for detailed explanation.
+> **See:** [ADR-001 Section 4.1: Middleware Execution Order](../architecture/ADR-001-architecture.md#41-middleware-execution-order-critical) and [ADR-015: Middleware Order Reference](../architecture/ADR-015-middleware-order.md) for detailed explanation.
 
 ---
 
@@ -275,7 +275,7 @@ end
 
 ### Dual-Buffer Architecture
 
-**E11y использует ДВА независимых буфера:**
+**E11y uses TWO independent buffers:**
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -318,15 +318,15 @@ Background Flush Thread (200ms interval):
 ### Buffer Routing Logic
 
 ```ruby
-# Pseudo-code для понимания
+# Pseudo-code for understanding
 def track_event(event)
   if event.severity == :debug && E11y.request_scope.active?
     # → Request-scoped buffer (Thread-local)
-    Thread.current[:e11y_request_buffer] << event
+    Thread.current[:e11y_ephemeral_buffer] << event
   else
     # → Main buffer (Global SPSC ring buffer)
     E11y.main_buffer << event
-    # Фоновый поток заберет через 200ms (или раньше если батч заполнится)
+    # Background thread will pick up in 200ms (or sooner if batch fills)
   end
 end
 ```
@@ -401,11 +401,17 @@ module E11y::RequestScope
 end
 ```
 
+> **DevLog integration (development/test):** When the debug buffer is flushed on request
+> failure, events are delivered to all registered adapters — including
+> `E11y::Adapters::DevLog` (auto-registered in development/test via Railtie). Debug
+> events from failed requests automatically appear in `log/e11y_dev.jsonl` and become
+> visible in the TUI and Browser Overlay. See [UC-017](UC-017-local-development.md).
+
 ---
 
 ## 📈 Performance Impact
 
-> **Implementation:** See [ADR-001 Section 8.3: Resource Limits](../ADR-001-architecture.md#83-resource-limits) for architectural details and [ADR-002 Section 6: Self-Monitoring](../ADR-002-metrics-yabeda.md#6-self-monitoring) for metrics implementation.
+> **Implementation:** See [ADR-001 Section 8.3: Resource Limits](../architecture/ADR-001-architecture.md#83-resource-limits) for architectural details and [ADR-002 Section 6: Self-Monitoring](../ADR-002-metrics-yabeda.md#6-self-monitoring) for metrics implementation.
 
 ### Buffer Metrics
 
@@ -413,20 +419,20 @@ end
 
 ```ruby
 # Exposed via Yabeda (auto-configured)
-Yabeda.e11y_request_buffer_size  # Gauge: current buffer size per request
-Yabeda.e11y_request_buffer_flushes_total  # Counter: buffer flushes by trigger
+Yabeda.e11y_ephemeral_buffer_size  # Gauge: current buffer size per request
+Yabeda.e11y_ephemeral_buffer_flushes_total  # Counter: buffer flushes by trigger
 
 # Accessible via Prometheus metrics endpoint
 # Example queries:
 
 # 1. Average buffer size
-avg(e11y_request_buffer_size)
+avg(e11y_ephemeral_buffer_size)
 
 # 2. Buffer flush rate by trigger
-rate(e11y_request_buffer_flushes_total{trigger="error"}[5m])
+rate(e11y_ephemeral_buffer_flushes_total{trigger="error"}[5m])
 
 # 3. Buffer overflow alerts
-e11y_request_buffer_size >= 100  # Alert if buffer limit reached
+e11y_ephemeral_buffer_size >= 100  # Alert if buffer limit reached
 ```
 
 **Monitoring Examples:**
@@ -436,18 +442,18 @@ e11y_request_buffer_size >= 100  # Alert if buffer limit reached
 
 # Panel 1: Buffer Size Distribution
 histogram_quantile(0.99, 
-  sum(rate(e11y_request_buffer_size[5m])) by (le)
+  sum(rate(e11y_ephemeral_buffer_size[5m])) by (le)
 )
 # Shows p99 buffer size
 
 # Panel 2: Flush Triggers Breakdown
 sum by (trigger) (
-  rate(e11y_request_buffer_flushes_total[5m])
+  rate(e11y_ephemeral_buffer_flushes_total[5m])
 )
 # Shows why buffers flush (error vs. slow_request vs. custom)
 
 # Panel 3: Memory Impact Estimate
-avg(e11y_request_buffer_size) * 500  # bytes per event
+avg(e11y_ephemeral_buffer_size) * 500  # bytes per event
 # Estimates per-request memory usage
 ```
 
@@ -609,13 +615,13 @@ end
 
 ---
 
-## 🔄 Взаимодействие с Flush Interval (200ms)
+## 🔄 Interaction with Flush Interval (200ms)
 
-### Вопрос: Не конфликтуют ли буферы?
+### Question: Do the buffers conflict?
 
-**Ответ: НЕТ. Они независимы.**
+**Answer: NO. They are independent.**
 
-### Детальная Логика
+### Detailed Logic
 
 ```ruby
 # config/initializers/e11y.rb
@@ -636,9 +642,9 @@ E11y.configure do |config|
 end
 ```
 
-### Поток Событий
+### Event Flow
 
-**Scenario 1: Обычный запрос (успешный)**
+**Scenario 1: Normal request (successful)**
 ```ruby
 # Request starts
 Events::DebugEvent.track(...)          # → Request buffer (thread-local)
@@ -650,7 +656,7 @@ Events::DebugEvent.track(...)          # → Request buffer (thread-local)
 # → Main buffer flushed every 200ms (success event sent)
 ```
 
-**Scenario 2: Запрос с ошибкой**
+**Scenario 2: Request with error**
 ```ruby
 # Request starts
 Events::DebugEvent.track(...)          # → Request buffer
@@ -662,20 +668,20 @@ Events::DebugEvent.track(...)          # → Request buffer
 # → Main buffer continues flush every 200ms (error event sent)
 ```
 
-**Scenario 3: Высоконагруженный сервис**
+**Scenario 3: High-load service**
 ```ruby
-# 1000 requests/sec, каждый с 5 debug events
-# → 5000 debug events/sec в request buffers (thread-local)
-# → 99% успешных → 4950 debug events/sec DISCARDED
-# → 1% ошибок → 50 debug events/sec FLUSHED
+# 1000 requests/sec, each with 5 debug events
+# → 5000 debug events/sec in request buffers (thread-local)
+# → 99% successful → 4950 debug events/sec DISCARDED
+# → 1% errors → 50 debug events/sec FLUSHED
 # 
-# Параллельно:
+# In parallel:
 # → 1000 info/success events/sec → Main buffer
-# → Flush каждые 200ms = 5 batches/sec
-# → 200 events per batch (в среднем)
+# → Flush every 200ms = 5 batches/sec
+# → 200 events per batch (on average)
 ```
 
-### Итого: Никакого Конфликта!
+### Summary: No Conflict!
 
 | Event Type | Buffer | Flush Trigger | Latency |
 |------------|--------|---------------|---------|
@@ -686,14 +692,14 @@ Events::DebugEvent.track(...)          # → Request buffer
 | `:error` | Main buffer (Global SPSC) | Every 200ms (background thread) | <200ms |
 | `:fatal` | Main buffer (Global SPSC) | Every 200ms (background thread) | <200ms |
 
-**Преимущества двойного буфера:**
-1. ✅ Debug события не засоряют main buffer
-2. ✅ Важные события (info+) идут быстро (200ms)
-3. ✅ Debug события идут мгновенно при ошибке (flush triggered)
-4. ✅ 99% debug событий вообще не обрабатываются (discard = zero cost)
-5. ✅ Thread-safety: request buffer изолирован в Thread.current
+**Benefits of dual buffer:**
+1. ✅ Debug events don't clutter main buffer
+2. ✅ Important events (info+) go fast (200ms)
+3. ✅ Debug events go instantly on error (flush triggered)
+4. ✅ 99% of debug events are never processed (discard = zero cost)
+5. ✅ Thread-safety: request buffer isolated in Thread.current
 
-### Визуальная Диаграмма
+### Visual Diagram
 
 ```
 Time: ──────────────────────────────────────────────────>
@@ -720,14 +726,14 @@ Background Flush Thread:   │  │
               200ms          400ms
 ```
 
-### Пример с Цифрами
+### Example with Numbers
 
-**Нагрузка:**
+**Load:**
 - 100 requests/sec
-- Каждый запрос: 3 debug события + 1 success событие
+- Each request: 3 debug events + 1 success event
 - Error rate: 1%
 
-**Что происходит:**
+**What happens:**
 
 | Time | Request Buffer (Thread-local) | Main Buffer (Global) | Flush |
 |------|------------------------------|---------------------|-------|
@@ -739,8 +745,8 @@ Background Flush Thread:   │  │
 | 210ms | Req21: [D, D, D] ERROR! | [S21, E21, **D, D, D from Req21**] | **Immediate flush debug** |
 | 400ms | - | [S21...S40] | **Flush next batch** |
 
-**Результат:**
-- Success events: ~100/sec → flush каждые 200ms → latency <200ms ✅
+**Result:**
+- Success events: ~100/sec → flush every 200ms → latency <200ms ✅
 - Debug events (99%): DISCARDED → zero overhead ✅
 - Debug events (1% errors): flushed IMMEDIATELY with error context ✅
 
@@ -804,7 +810,7 @@ end
 
 - **[UC-002: Business Event Tracking](./UC-002-business-event-tracking.md)** - Define structured events
 - **[UC-010: Background Job Tracking](./UC-010-background-job-tracking.md)** - Buffering in Sidekiq/ActiveJob
-- **[UC-015: Local Development](./UC-015-local-development.md)** - Test buffering locally
+- **[UC-017: Local Development](./UC-017-local-development.md)** - Test buffering locally
 
 ---