e11y 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c2fbfb3af2fb95f263bbd3e7068b9096bb3fda318142963d90367e0feabfb9d
-  data.tar.gz: 433928d7153ffce185577c99d82a31a63a25f0720b7c2ea7c27a306425c8abce
+  metadata.gz: 9d7e79dcbcbd63a42a108fff3b2c29f4cea6f07e8e2632145d4cff39f85514ac
+  data.tar.gz: b53a0b131efaad3accb9ab20b75c5dcf973274422d384432a3b3562437750e4b
 SHA512:
-  metadata.gz: 9119ba005f1b8be835aa331e50ecf0ab9c52c8dd13e14c2b9bdfa9f5af3c4341937a9c9f1b7c30b8d43c31b7287d1632221e67c82380b882c770a94af7cf2bbf
-  data.tar.gz: c29c35fffbc7c959cc56e1774338c8717cde744c677d38c98bd308cf96487a8ebe2a57690e82808afec347b5f48497e4ea0536e9067b413c3fa39776f655f266
+  metadata.gz: 4576c625410acc475dbd5782fa546b29adcc6a815c319d86eae9a9b8e0a700c49a099197db7fdccf3c3ea43f594c24bdd90ccdc689cad82e9a8da11d18d50999
+  data.tar.gz: f569447a2c1b532cc39246d163fe245b61f63ec9ee618a2c9cf428936f3eead760549d6774de9b8a5afc09d12a0df7439ad53bf0f41993a7c518af566ebbdc1d

data/.rubocop.yml

@@ -3,14 +3,10 @@
 # See https://rubystyle.guide/ for Ruby style guide
 # See https://docs.rubocop.org/rubocop/ for all available cops
 
-require:
-  - rubocop-rspec
-  - rubocop-rspec_rails
-
 plugins:
-  - rubocop-capybara
-  - rubocop-factory_bot
   - rubocop-performance
+  - rubocop-rspec
+  - rubocop-rspec_rails
 
 AllCops:
   TargetRubyVersion: 3.2
@@ -28,17 +24,82 @@ Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
     - 'Rakefile'
+    - 'lib/tasks/**/*'
     - '*.gemspec'
+    - 'lib/e11y/reliability/retry_handler.rb'
+    - 'lib/e11y/instruments/active_job.rb'
 
 Metrics/MethodLength:
-  Max: 15
+  Max: 20
   Exclude:
     - 'spec/**/*'
+    - 'lib/e11y/adapters/yabeda.rb'
+    - 'lib/e11y/middleware/routing.rb'
+    - 'lib/e11y/event/base.rb'
+    - 'lib/e11y/middleware/rate_limiting.rb'
+    - 'lib/e11y/middleware/sampling.rb'
 
 Metrics/ClassLength:
   Max: 100
   Exclude:
     - 'spec/**/*'
+    - 'lib/e11y/buffers/ephemeral_buffer.rb'
+    - 'lib/e11y/registry.rb'
+    - 'lib/e11y/adapters/otel_logs.rb'
+    - 'lib/e11y/adapters/opentelemetry_collector.rb'
+    - 'lib/e11y/opentelemetry/span_creator.rb'
+    - 'lib/e11y/configuration.rb'
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+  Exclude:
+    - 'lib/e11y/adapters/yabeda.rb'
+    - 'lib/e11y/middleware/event_slo.rb'
+    - 'lib/e11y/middleware/routing.rb'
+    - 'spec/integration/pattern_metrics_integration_spec.rb'
+    - 'spec/integration/slo_tracking_integration_spec.rb'
+    - 'spec/support/integration_helpers.rb'
+    - 'spec/support/integration/pii_helpers.rb'
+    - 'spec/support/loki_helpers.rb'
+    - 'spec/support/matchers/pii_matchers.rb'
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - 'lib/e11y/middleware/event_slo.rb'
+    - 'lib/e11y/middleware/routing.rb'
+    - 'lib/e11y/adapters/yabeda.rb'
+    - 'lib/e11y/event/base.rb'
+    - 'lib/e11y/middleware/versioning.rb'
+    - 'lib/e11y/reliability/retry_handler.rb'
+    - 'lib/e11y/adapters/base.rb'
+    - 'lib/e11y/adapters/opentelemetry_collector.rb'
+    - 'lib/e11y/adapters/otel_logs.rb'
+    - 'lib/e11y/current.rb'
+    - 'lib/e11y/instruments/active_job.rb'
+    - 'lib/e11y/instruments/sidekiq.rb'
+    - 'lib/e11y/linters/pii/pii_declaration_linter.rb'
+    - 'lib/e11y/linters/slo/config_consistency_linter.rb'
+    - 'lib/e11y/logger/bridge.rb'
+    - 'lib/e11y/middleware/pii_filter.rb'
+    - 'lib/e11y/middleware/rate_limiting.rb'
+    - 'lib/e11y/middleware/sampling.rb'
+    - 'lib/e11y/opentelemetry/span_creator.rb'
+    - 'spec/integration/slo_tracking_integration_spec.rb'
+    - 'spec/support/integration_helpers.rb'
+    - 'spec/support/integration/pii_helpers.rb'
+    - 'spec/support/loki_helpers.rb'
+    - 'spec/support/matchers/pii_matchers.rb'
+
+Metrics/PerceivedComplexity:
+  Max: 15
+  Exclude:
+    - 'lib/e11y/middleware/event_slo.rb'
+    - 'spec/integration/slo_tracking_integration_spec.rb'
+    - 'spec/support/integration_helpers.rb'
+    - 'spec/support/integration/pii_helpers.rb'
+    - 'spec/support/loki_helpers.rb'
+    - 'spec/support/matchers/pii_matchers.rb'
 
 # Style
 Style/Documentation:
@@ -52,9 +113,15 @@ Style/StringLiterals:
 Style/FrozenStringLiteralComment:
   Enabled: true
 
+# Layout
+Layout/LineLength:
+  Max: 150
+
 # RSpec
 RSpec/ExampleLength:
-  Max: 20 # Allow longer examples for integration tests
+  Max: 40 # Allow longer examples for integration tests
+  Exclude:
+    - "spec/integration/**/*"
 
 RSpec/MultipleExpectations:
   Max: 10 # Allow more expectations for integration tests
@@ -64,16 +131,43 @@ RSpec/MultipleMemoizedHelpers:
 
 RSpec/NestedGroups:
   Max: 3
+  Exclude:
+    - "spec/e11y/current_spec.rb"
+    - "spec/e11y/middleware/pii_filtering_spec.rb"
 
 # Gem-specific: Development dependencies can be in gemspec
 Gemspec/DevelopmentDependencies:
   Enabled: false
 
+Style/OneClassPerFile:
+  Exclude:
+    - "spec/dummy/config/application.rb"
+    - "spec/support/pipeline_debug.rb"
+
 # Allow integration tests without specific class
 RSpec/DescribeClass:
   Exclude:
     - "spec/zeitwerk_spec.rb"
     - "spec/integration/**/*"
+    - "spec/e11y/module_api_spec.rb"
+    - "spec/e11y/configuration/error_handling_config_spec.rb"
+
+# File path conventions (generators use spec/generators/e11y/ structure)
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - "spec/e11y/event/dsl_additions_spec.rb"
+    - "spec/e11y/module_api_spec.rb"
+    - "spec/generators/e11y/*_spec.rb"
+    - "spec/e11y/opentelemetry/semantic_conventions_spec.rb"
+    - "spec/e11y/opentelemetry/span_creator_spec.rb"
+
+RSpec/DescribeMethod:
+  Exclude:
+    - "spec/e11y/module_api_spec.rb"
+
+RSpec/MultipleDescribes:
+  Exclude:
+    - "spec/e11y/adapters/null_adapter_spec.rb"
 
 # Allow simple doubles for now (will improve in Phase 1)
 RSpec/VerifiedDoubles:
@@ -85,5 +179,31 @@ RSpec/VerifiedDoubles:
 RSpec/MessageSpies:
   Enabled: false
 
-Capybara/RSpec/PredicateMatcher:
-  Enabled: false
+# RSpec/Output: New cop in rubocop-rspec 3.x flagging puts in specs.
+# We use puts for diagnostic output in integration tests and support files.
+RSpec/Output:
+  Enabled: false
+
+RSpec/RepeatedExample:
+  Exclude:
+    - "spec/e11y/instruments/rails_instrumentation_spec.rb"
+    - "spec/e11y/versioning/version_extractor_spec.rb"
+
+RSpec/StubbedMock:
+  Exclude:
+    - "spec/e11y/module_api_spec.rb"
+    - "spec/e11y/slo/config_loader_spec.rb"
+
+Metrics/ParameterLists:
+  Exclude:
+    - "lib/e11y/adapters/opentelemetry_collector.rb"
+    - "lib/e11y/adapters/otel_logs.rb"
+
+Style/SafeNavigationChainLength:
+  Exclude:
+    - "lib/e11y/linters/pii/pii_declaration_linter.rb"
+
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - "lib/e11y/middleware/pii_filter.rb"
+

data/CHANGELOG.md

@@ -19,6 +19,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+## [1.0.0] - 2026-03-20
+
+### BREAKING: Configuration — Flat config API
+
+**Nested config objects removed.** All configuration options are now flat accessors on `config`.
+
+**Key migrations:**
+- `config.rails_instrumentation.enabled` → `config.rails_instrumentation_enabled`
+- `config.logger_bridge.track_severities` → `config.logger_bridge_track_severities`
+- `config.rate_limiting { }` removed → use `config.rate_limiting_enabled`, `config.add_rate_limit_per_event(...)`
+- `config.slo { }` removed → use `config.slo_tracking_enabled`, `config.add_slo_controller(...)`
+
+**Full mapping:** See `docs/plans/2026-03-13-configuration-design.md`
+
+### BREAKING: Middleware order changed (ADR-015 compliance)
+
+**Per ADR-015 and ADR-006:**
+- **Versioning** moved to last (before Routing) — Validation, PII, RateLimiting, Sampling now use original class names
+- **AuditSigning** before PIIFilter — audit events signed with original data (GDPR Art. 30 non-repudiation)
+- **RateLimiting** before Sampling — matches ADR #4, #5
+
+**New order:** TraceContext → Validation → AuditSigning → PIIFilter → RateLimiting → Sampling → Versioning → Routing → EventSlo
+
+**Migration:** If you custom-configured pipeline order, ensure Versioning is last before Routing. Audit events now receive unfiltered payload at signing.
+
+### BREAKING: Registry.all_events → Registry.event_classes
+
+**Renamed for clarity:** Method returns event classes, not event instances or names.
+
+**Migration:** `E11y::Registry.all_events` → `E11y::Registry.event_classes`
+
+### BREAKING: RequestScopedBuffer → EphemeralBuffer
+
+**Renamed for accuracy:** The buffer works for both HTTP requests and background jobs. "Ephemeral" reflects its temporary lifecycle.
+
+**Migration:**
+- `E11y::Buffers::RequestScopedBuffer` → `E11y::Buffers::EphemeralBuffer`
+- `config.request_buffer` → `config.ephemeral_buffer`
+- `Thread.current[:e11y_request_buffer]` → `Thread.current[:e11y_ephemeral_buffer]`
+- Yabeda metric `e11y_request_buffer_total` → `e11y_ephemeral_buffer_total`
+
+**Search and replace:** `RequestScopedBuffer` → `EphemeralBuffer`, `request_buffer` → `ephemeral_buffer`
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Deprecated
+
+### Removed
+
+### Security
+
 ## [0.2.0] - 2026-01-26
 
 ### Added
@@ -135,7 +190,7 @@ Initial release of E11y - Event-driven observability for Rails applications.
   - Audit log (encrypted storage)
 
 - **Advanced Features**
-  - Pattern-based metrics extraction
+  - Event-level metrics (metrics DSL)
   - PII filtering with configurable rules
   - Stratified sampling
   - Rate limiting

data/CLAUDE.md

@@ -0,0 +1,168 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+E11y ("easy telemetry") is a Ruby gem providing observability for Rails apps. Its key differentiator is **request-scoped debug buffering**: debug logs accumulate in memory during a request and flush to storage only if the request fails, cutting noise by ~90%.
+
+- **Ruby**: 3.2+, **Rails**: 7.0–8.0 (8.1 excluded due to a sqlite3 bug)
+- **Gem version**: 0.2.0, current branch: `feat/integration-testing`
+
+## Commands
+
+```bash
+# Run all tests
+rake spec:all
+
+# Run unit tests only (fast, no Rails required)
+rake spec:unit
+
+# Run integration tests (requires --with integration bundle group)
+rake spec:integration
+
+# Integration tests for Loki/OTel adapters require services — start with docker compose:
+docker compose up -d loki otel-collector
+INTEGRATION=true bundle exec rspec spec/integration/critical_adapters_integration_spec.rb
+
+# Run a single spec file
+bundle exec rspec spec/e11y/adapters/loki_adapter_spec.rb
+
+# Run a single example by line number
+bundle exec rspec spec/e11y/adapters/loki_adapter_spec.rb:42
+
+# Lint
+bundle exec rubocop
+
+# Lint with autocorrect
+bundle exec rubocop -a
+
+# Install integration dependencies (needed before rake spec:integration)
+bundle install --with integration
+
+# Open a console with the gem loaded
+rake console
+
+# Run benchmarks
+rake spec:benchmark
+
+# Run Cucumber acceptance tests
+rake cucumber
+# Or: bundle exec cucumber features/
+
+# Cucumber with Loki (adapter_configurations.feature): start Loki + OTel first
+docker compose up -d loki otel-collector
+rake cucumber
+
+# Run TUI (interactive log viewer)
+bundle exec e11y
+
+# Start MCP server (for Cursor / Claude Code)
+bundle exec e11y mcp
+
+# Stream events to stdout
+bundle exec e11y tail
+```
+
+## Architecture
+
+### Event Processing Pipeline
+
+Every event flows through a middleware pipeline before reaching an adapter:
+
+```
+Event.track(data)
+  → Validation (dry-schema)
+  → Sampling (adaptive: error-spike, load, value-based)
+  → PII Filtering (mask/hash sensitive fields)
+  → Trace Context (attach OTel span/trace IDs)
+  → Routing (direct to adapters by severity/type)
+  → Rate Limiting
+  → Audit Signing
+  → Adapter(s): Loki | Sentry | OpenTelemetry | Yabeda | File | Stdout | InMemory
+```
+
+Pipeline is built in `lib/e11y/pipeline/builder.rb`. Middleware order matters — see ADR-015.
+
+### Key Modules
+
+| Path | Role |
+|------|------|
+| `lib/e11y.rb` | Public API, `E11y.configure`, `E11y.configuration`, `E11y.logger` |
+| `lib/e11y/event/base.rb` | Base event class; all user events inherit from this |
+| `lib/e11y/adapters/` | Backend adapters (Loki, Sentry, OTel, Yabeda, File, Stdout, InMemory) |
+| `lib/e11y/middleware/` | 11 pipeline stages (validation, sampling, PII, routing, etc.) |
+| `lib/e11y/buffers/` | Request-scoped buffer + adaptive buffer implementations |
+| `lib/e11y/pipeline/builder.rb` | Assembles middleware chain from configuration |
+| `lib/e11y/railtie.rb` | Rails integration entry point |
+| `lib/e11y/pii/` | PII detection patterns and masking/hashing strategies |
+| `lib/e11y/sampling/` | Error-spike, load-based, value-based sampling strategies |
+| `lib/e11y/reliability/` | Circuit breaker, DLQ (dead letter queue), retry logic |
+| `lib/e11y/slo/` | Event-driven SLO tracking |
+| `lib/e11y/metrics/` | Prometheus metrics registry with cardinality protection |
+| `gems/e11y-devtools/` | Developer tools gem (TUI, Browser Overlay, MCP) — dev-only |
+| `gems/e11y-devtools/lib/e11y/devtools/tui/` | ratatui_ruby TUI — interaction-centric log viewer |
+| `gems/e11y-devtools/lib/e11y/devtools/overlay/` | Rails Engine — floating badge + slide-in panel |
+| `gems/e11y-devtools/lib/e11y/devtools/mcp/` | MCP Server — AI integration for Cursor/Claude Code |
+| `lib/e11y/adapters/dev_log.rb` | DevLog adapter — JSONL write+read, shared by all viewers |
+
+### Event Definition Pattern
+
+Events are defined as classes inheriting from `E11y::Event::Base`:
+
+```ruby
+class Events::OrderCreated < E11y::Event::Base
+  schema do
+    required(:order_id).filled(:string)
+    required(:amount).filled(:float)
+    optional(:user_id).maybe(:string)
+  end
+
+  metrics do
+    counter :orders_created_total, "Orders created"
+    histogram :order_amount, "Order amount in USD", buckets: [10, 50, 100, 500]
+  end
+end
+
+# Usage
+Events::OrderCreated.track(order_id: order.id, amount: order.total)
+```
+
+### Adapter Routing
+
+Adapters are registered in configuration and events route to them by severity:
+- `error`/`fatal` → errors tracker (e.g., Sentry)
+- other severities → logs (e.g., Loki)
+- metrics always → Yabeda/Prometheus
+
+### Request-Scoped Buffering
+
+The buffer middleware captures debug-level events in a `Concurrent::Array` per request (stored in `Thread.current`). On request success: buffer discarded. On request failure: buffer flushed to configured adapters. Controlled by `config.ephemeral_buffer_enabled`.
+
+## Test Structure
+
+- `spec/e11y/` — Unit tests (86 files, ~1672 examples, fast)
+- `spec/integration/` — Integration tests against a real Rails app (~36 examples)
+- `spec/dummy/` — Minimal Rails app used by integration tests
+- `spec/dummy/app/events/events/` — Event class definitions for test fixtures
+- `spec/support/matchers/` — Custom RSpec matchers including PII matchers
+- `spec/fixtures/pii_samples.yml` — PII test data
+
+Integration tests use `DatabaseCleaner` and require `--with integration` bundle group.
+
+## Code Conventions
+
+- Frozen string literals everywhere (`# frozen_string_literal: true`)
+- Double-quoted strings (enforced by RuboCop)
+- Events use class-level `.track` (not instantiation) — zero-allocation design; data stored in plain Hashes
+- Adapters inherit from `E11y::Adapters::Base` and implement `#deliver(event_data)`
+- Middleware inherits from `E11y::Middleware::Base` and implements `#call(event, pipeline)`
+
+## Architecture Decision Records
+
+The `docs/architecture/ADR-*.md` files document design decisions. Key ones:
+- **ADR-004**: Adapter architecture
+- **ADR-011**: Testing strategy
+- **ADR-013**: Reliability and error handling
+- **ADR-015**: Middleware ordering (critical — changing order breaks the pipeline)
+- **ADR-017**: Multi-Rails compatibility approach