e11y 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae952b91e779ee9e04150e324109586016d6dd0e9831d6acf7867e05f686f579
+  data.tar.gz: 8c3a957e11bd4cc84b4f5fa9c90eae3248c083b98a518ee328cad76401d5454b
+SHA512:
+  metadata.gz: ce56d9787c13db96db175a07418a34b17a43dd11dceb23d463c346abb7082caa1c45151826f6dc59981a069d8f2ec10d0f6eb4516f2da8cbce91754c483bae20
+  data.tar.gz: b5b650f09a2b634e31fedcebd058965dbc9787960769387b12a84bb5c14c96eb68bcc3245d04393bb75d51011dd290064185040daddcbc975aa8a66f6bda1709

data/.rspec

@@ -0,0 +1,4 @@
+--require spec_helper
+--format documentation
+--color
+--order random

data/.rubocop.yml

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# See https://rubystyle.guide/ for Ruby style guide
+# See https://docs.rubocop.org/rubocop/ for all available cops
+
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'tmp/**/*'
+
+# Metrics
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 15
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Max: 100
+  Exclude:
+    - 'spec/**/*'
+
+# Style
+Style/Documentation:
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+# RSpec
+RSpec/ExampleLength:
+  Max: 20 # Allow longer examples for integration tests
+
+RSpec/MultipleExpectations:
+  Max: 10 # Allow more expectations for integration tests
+
+RSpec/NestedGroups:
+  Max: 3
+
+# Gem-specific: Development dependencies can be in gemspec
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Allow integration tests without specific class
+RSpec/DescribeClass:
+  Exclude:
+    - "spec/zeitwerk_spec.rb"
+
+# Allow simple doubles for now (will improve in Phase 1)
+RSpec/VerifiedDoubles:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial gem skeleton setup
+- Zeitwerk autoloading configuration
+- Basic project structure (lib/, spec/, bin/)
+- CI/CD pipeline (GitHub Actions)
+- Documentation framework (YARD, README)
+
+## [0.1.0] - 2026-01-17
+
+### Added
+- Project initialization
+- Phase 0: Gem Setup & Best Practices Research complete
+- Research documents for 6 successful gems (Devise, Sidekiq, Puma, Dry-rb, Yabeda, Sentry)
+- Best practices synthesis for configuration DSL, testing, documentation, CI/CD, release process
+
+[Unreleased]: https://github.com/arturseletskiy/e11y/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/arturseletskiy/e11y/releases/tag/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,64 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at team@e11y.dev.
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artur Seletskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# E11y - Easy Telemetry for Ruby on Rails
+
+[![Gem Version](https://badge.fury.io/rb/e11y.svg)](https://badge.fury.io/rb/e11y)
+[![Build Status](https://github.com/arturseletskiy/e11y/workflows/CI/badge.svg)](https://github.com/arturseletskiy/e11y/actions)
+[![Code Coverage](https://codecov.io/gh/arturseletskiy/e11y/branch/main/graph/badge.svg)](https://codecov.io/gh/arturseletskiy/e11y)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+
+**Production-ready observability for Rails applications.**
+
+E11y (Easy Telemetry) provides structured business event tracking with request-scoped debug buffering, pattern-based metrics, zero-config SLO tracking, and pluggable adapters for logs/metrics/traces. Designed for SuperApp architecture with compliance-ready PII filtering and audit trails.
+
+## 🚀 Quick Start
+
+```ruby
+# Gemfile
+gem "e11y"
+
+# Define your first event
+class OrderPaidEvent < E11y::Event::Base
+  schema do
+    required(:order_id).filled(:integer)
+    required(:amount).filled(:float)
+  end
+  
+  severity :success  # Optional - auto-detected from name
+  adapters :loki     # Optional - auto-selected based on severity
+end
+
+# Track events (zero-allocation pattern)
+OrderPaidEvent.track(order_id: 123, amount: 99.99)
+```
+
+## ✨ Features
+
+- 🎯 **Zero-Allocation Event Tracking** - Class-based pattern with zero GC pressure
+- 📐 **Convention over Configuration** - Smart defaults from event names
+- 📊 **Type-Safe Events** - Declarative schemas with dry-schema validation
+- 🔄 **Event Versioning** - Built-in version support for schema evolution
+- 🎭 **Severity Levels** - Auto-detection from event names
+- 🔌 **Pluggable Adapters** - Loki, Sentry, OpenTelemetry, File, Stdout, Memory
+- 📦 **Future Ready** - Architecture designed for Phase 2+ features:
+  - Request-Scoped Debug Buffering
+  - Pattern-Based Metrics (Prometheus/Yabeda)
+  - PII Filtering & Audit Trails (GDPR/SOC2)
+  - Rate Limiting & Cardinality Protection
+  - OpenTelemetry Integration
+  - Rails/Sidekiq Integration
+
+## 📚 Documentation
+
+- [Quick Start Guide](docs/QUICK-START.md)
+- [Implementation Plan](docs/IMPLEMENTATION_PLAN.md)
+- [Architecture Decisions (ADRs)](docs/)
+- [Use Cases](docs/use_cases/)
+- [API Reference](https://e11y.dev/api)
+
+## 🛠️ Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "e11y"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install e11y
+```
+
+## 📖 Usage
+
+### Define Events
+
+```ruby
+# Convention-based configuration (minimal)
+class UserSignupEvent < E11y::Event::Base
+  schema do
+    required(:user_id).filled(:integer)
+    required(:email).filled(:string)
+  end
+  # Severity auto-detected: :info
+  # Adapters auto-selected: [:loki]
+end
+
+# Explicit configuration
+class PaymentFailedEvent < E11y::Event::Base
+  severity :error           # Explicit severity
+  version 2                 # Event version
+  adapters :loki, :sentry   # Multiple adapters
+  
+  schema do
+    required(:payment_id).filled(:integer)
+    required(:error_code).filled(:string)
+  end
+end
+
+# Track events (class method - no instances!)
+UserSignupEvent.track(user_id: 123, email: "user@example.com")
+PaymentFailedEvent.track(payment_id: 456, error_code: "CARD_DECLINED")
+```
+
+### Convention-Based Defaults
+
+E11y uses smart conventions to minimize configuration:
+
+**Severity from event name:**
+- `*Failed*`, `*Error*` → `:error`
+- `*Paid*`, `*Success*`, `*Completed*` → `:success`
+- `*Warn*`, `*Warning*` → `:warn`
+- Default → `:info`
+
+**Adapters from severity:**
+- `:error`, `:fatal` → `[:loki, :sentry]` (errors need both logging and alerting)
+- Others → `[:loki]` (logs only)
+
+**Result:** 90% of events need only `schema` definition!
+
+## 🧪 Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Run security audit
+bundle exec bundler-audit check --update
+bundle exec brakeman
+
+# Generate documentation
+bundle exec yard doc
+```
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/arturseletskiy/e11y. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+
+## 📜 License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## 🙏 Code of Conduct
+
+Everyone interacting in the E11y project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## 📊 Project Status
+
+**Current Version:** 0.1.0
+
+**Phase 1 Progress (In Development):**
+- ✅ Phase 0: Gem Setup & Best Practices
+- 🔄 Phase 1: Core Foundation (In Progress)
+  - ✅ Event::Base with zero-allocation pattern
+  - ✅ Convention-based configuration
+  - ✅ Schema validation (dry-schema)
+  - 🔄 Adaptive Buffer implementation
+  - ⏳ Middleware Pipeline
+  - ⏳ track() method with pipeline
+
+**Next Phases:**
+- ⏳ Phase 2: Core Features (PII, Adapters, Metrics)
+- ⏳ Phase 3: Rails Integration
+- ⏳ Phase 4: Production Hardening
+- ⏳ Phase 5: Scale & Optimization
+
+See [IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md) for detailed timeline.

data/Rakefile

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+# Custom tasks
+namespace :e11y do
+  desc "Start interactive console"
+  task :console do
+    require "pry"
+    require_relative "lib/e11y"
+    Pry.start
+  end
+
+  desc "Run performance benchmarks"
+  task :benchmark do
+    ruby "spec/benchmarks/run_all.rb"
+  end
+
+  desc "Generate documentation"
+  task :docs do
+    sh "yard doc"
+  end
+
+  desc "Run security audit"
+  task :audit do
+    sh "bundle exec bundler-audit check --update"
+    sh "bundle exec brakeman --no-pager"
+  end
+end

data/benchmarks/run_all.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# E11y Benchmarks Runner
+#
+# Run all benchmarks:
+#   bundle exec ruby benchmarks/run_all.rb
+#
+# Run with specific iterations:
+#   ITERATIONS=10000 bundle exec ruby benchmarks/run_all.rb
+
+require "bundler/setup"
+require "benchmark"
+require "e11y"
+
+ITERATIONS = (ENV["ITERATIONS"] || 1000).to_i
+
+puts "🚀 E11y Benchmarks (#{ITERATIONS} iterations)"
+puts "=" * 60
+
+# Benchmarks will be implemented in Phase 1+
+# Examples:
+# - Event creation (zero-allocation goal)
+# - Buffer operations (push/flush)
+# - Middleware chain execution
+# - Adapter send performance
+
+puts "\n⚠️  Benchmarks will be implemented in Phase 1+"
+puts "Expected metrics (from ADR-009):"
+puts "  - Event creation: < 10µs per event (zero-allocation)"
+puts "  - Buffer push: < 1µs (lock-free)"
+puts "  - Middleware: < 5µs per middleware"
+puts "  - Memory: < 100KB baseline, < 10MB under load"

data/config/README.md

@@ -0,0 +1,83 @@
+# Docker Compose Test Backends
+
+This Docker Compose setup provides test backends for E11y integration testing.
+
+## Services
+
+| Service | Port | Purpose | Health Check |
+|---------|------|---------|--------------|
+| **Loki** | 3100 | Log aggregation | http://localhost:3100/ready |
+| **Prometheus** | 9090 | Metrics collection | http://localhost:9090/-/healthy |
+| **Elasticsearch** | 9200 | Log storage & search | http://localhost:9200/_cluster/health |
+| **Redis** | 6379 | Caching & pub/sub | redis-cli ping |
+
+## Usage
+
+### Start all backends:
+```bash
+docker-compose up -d
+```
+
+### Check status:
+```bash
+docker-compose ps
+```
+
+### View logs:
+```bash
+docker-compose logs -f [service_name]
+```
+
+### Stop all backends:
+```bash
+docker-compose down
+```
+
+### Stop and remove volumes:
+```bash
+docker-compose down -v
+```
+
+## Configuration Files
+
+- `config/loki-local-config.yaml` - Loki configuration
+- `config/prometheus.yml` - Prometheus scrape configuration
+
+## Integration Testing
+
+These backends are used for:
+- **Loki**: Testing `E11y::Adapters::LokiAdapter` (Phase 3)
+- **Prometheus**: Testing Yabeda metrics integration (Phase 1)
+- **Elasticsearch**: Testing `E11y::Adapters::ElasticsearchAdapter` (Phase 3)
+- **Redis**: Testing rate limiting, caching (Phase 1)
+
+## Resource Requirements
+
+- **Memory**: ~2GB RAM total
+- **Disk**: ~500MB for images + data volumes
+- **Network**: Bridge network `e11y_network`
+
+## Health Checks
+
+All services include health checks with automatic retries:
+- Loki: 10s interval, 5 retries
+- Prometheus: 10s interval, 5 retries
+- Elasticsearch: 10s interval, 10 retries (slower startup)
+- Redis: 5s interval, 5 retries
+
+## Troubleshooting
+
+### Elasticsearch fails to start:
+```bash
+# Increase vm.max_map_count on Linux/macOS
+sysctl -w vm.max_map_count=262144
+```
+
+### Port conflicts:
+Edit `docker-compose.yml` and change port mappings.
+
+## Production Note
+
+⚠️ **This is for TESTING ONLY!** Do not use these configurations in production.
+
+For production setup, see `docs/guides/production-deployment.md` (Phase 5).

data/config/loki-local-config.yaml

@@ -0,0 +1,35 @@
+auth_enabled: false
+
+server:
+  http_listen_port: 3100
+  grpc_listen_port: 9096
+
+common:
+  path_prefix: /tmp/loki
+  storage:
+    filesystem:
+      chunks_directory: /tmp/loki/chunks
+      rules_directory: /tmp/loki/rules
+  replication_factor: 1
+  ring:
+    instance_addr: 127.0.0.1
+    kvstore:
+      store: inmemory
+
+schema_config:
+  configs:
+    - from: 2020-10-24
+      store: boltdb-shipper
+      object_store: filesystem
+      schema: v11
+      index:
+        prefix: index_
+        period: 24h
+
+ruler:
+  alertmanager_url: http://localhost:9093
+
+# By default, Loki will send anonymous usage data to Grafana Labs.
+# To disable, set false.
+analytics:
+  reporting_enabled: false

data/config/prometheus.yml

@@ -0,0 +1,15 @@
+global:
+  scrape_interval: 15s
+  evaluation_interval: 15s
+
+scrape_configs:
+  - job_name: 'prometheus'
+    static_configs:
+      - targets: ['localhost:9090']
+  
+  - job_name: 'e11y-metrics'
+    static_configs:
+      - targets: ['host.docker.internal:9394']
+        labels:
+          app: 'e11y'
+          environment: 'test'

data/docker-compose.yml

@@ -0,0 +1,78 @@
+version: '3.8'
+
+services:
+  loki:
+    image: grafana/loki:2.9.0
+    container_name: e11y_loki
+    ports:
+      - "3100:3100"
+    volumes:
+      - ./config/loki-local-config.yaml:/etc/loki/local-config.yaml
+    command: -config.file=/etc/loki/local-config.yaml
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3100/ready"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - e11y_network
+
+  prometheus:
+    image: prom/prometheus:v2.45.0
+    container_name: e11y_prometheus
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./config/prometheus.yml:/etc/prometheus/prometheus.yml
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:9090/-/healthy"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - e11y_network
+
+  elasticsearch:
+    image: elasticsearch:8.9.0
+    container_name: e11y_elasticsearch
+    ports:
+      - "9200:9200"
+      - "9300:9300"
+    environment:
+      - discovery.type=single-node
+      - xpack.security.enabled=false
+      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9200/_cluster/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    networks:
+      - e11y_network
+
+  redis:
+    image: redis:7-alpine
+    container_name: e11y_redis
+    ports:
+      - "6379:6379"
+    command: redis-server --appendonly yes
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+    volumes:
+      - redis_data:/data
+    networks:
+      - e11y_network
+
+networks:
+  e11y_network:
+    driver: bridge
+
+volumes:
+  redis_data:
+    driver: local