rails_error_dashboard 0.10.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7065559d38e3152511024cd4a44698c3b215cc6cd60e4917d52cf4d893180b6c
-  data.tar.gz: 0d9237d4e89f4cb08392aecfe109dbb38bc1aaf673e834d827441bebf84a6e3f
+  metadata.gz: 4aa6cdee526bf9210f3762861a373dbefbe99b9ed94ecdb5f6464fb781bdddb4
+  data.tar.gz: 3a7977ff26332c869b5bf6e4e5316d3470e978ff736184dcc4119f0982822c4c
 SHA512:
-  metadata.gz: 996b72e8406365ca4ee064464faa785b7a43dfa5f643ed9f2ca3be39d4d98b3dd13ed6426a1dbef3eb53fad3d6433d89b70b3f8a3d8e40434aad1e882cff0eb1
-  data.tar.gz: 4814ed8949397ce5ca0cd27cf4e9f52f5ba2e5bf243eff411eb0e7c80539fef978c0dc87505c02bb0e2a259725a8fec97a5897c62073eae2a9142c0f0b2c2ea8
+  metadata.gz: ea46f47e2e96da83cf0c83d94596e63d63ab0dafeea5a3f696b2a1021b9eb57026485c9fec4d0827e8f8fcd4852fd587a69d28d3890ec14a5ec295d549826264
+  data.tar.gz: 4ea0ff21bbcb9177fd43297a5145e17a6316ec52f2f8a5370b30e36879a32810cd289b22e7c1d66abb2b9f9a66593bc2e013ab3ccfc19af1c0ffc46c42863537

data/README.md

@@ -7,27 +7,100 @@
 [![Sponsor](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/AnjanJ)
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/anjanj)
 
-**Self-hosted Rails error monitoring — free, forever.**
+**Rails-native error tracking for failure investigation — see the Ruby state and Rails runtime health behind every exception. Self-hosted, inside your app, in your own database. The gem is MIT and free forever.**
 
 ```ruby
-gem 'rails_error_dashboard'
+gem "rails_error_dashboard"
 ```
 
-**5-minute setup** · **Works out-of-the-box** · **PostgreSQL, MySQL/Trilogy, SQLite — shared or separate database** · **No vendor lock-in**
+```bash
+bundle install
+rails generate rails_error_dashboard:install
+rails db:migrate
+```
 
-[Full Documentation](https://anjanj.github.io/rails_error_dashboard/) · [Live Demo](https://rails-error-dashboard.anjan.dev) · [RubyGems](https://rubygems.org/gems/rails_error_dashboard)
+Open `/red` and raise a test exception. No monitoring account or ingestion service is required.
 
----
+[Try the live demo](https://rails-error-dashboard.anjan.dev) (`gandalf` / `youshallnotpass`) · [Read the documentation](https://anjanj.github.io/rails_error_dashboard/) · [View on RubyGems](https://rubygems.org/gems/rails_error_dashboard)
+
+> **Beta:** RED is functional and extensively tested, but configuration and APIs may change before 1.0. Supports Rails 7.0–8.1 and Ruby 3.2–4.0 (CI runs Ruby 3.2–3.4 against every supported Rails version; Ruby 4.0 is verified by the maintainer).
+
+## See the Ruby state and Rails runtime health behind every exception
+
+Rails Error Dashboard (RED) is an open-source, self-hosted Rails engine for investigating production failures. It helps you answer not only **what failed**, but **what was happening inside Ruby and Rails when it failed**.
+
+- Inspect local variables and the raising object's instance variables before the stack unwinds.
+- See error-time Active Record, Puma, job queue, GC, memory and process health.
+- Follow the SQL, cache, controller, job, mailer and other Rails events leading to the exception.
+- Stay safe during error floods with progressive, count-preserving storm protection.
+- Keep exception data on infrastructure you control.
+
+![Local and instance variables captured at the raise, scrubbed with filter_parameters](docs/images/local-variables.png)
+
+## The questions RED helps you answer
+
+A stack trace tells you where execution stopped. RED helps you investigate the state behind it:
+
+- What did `params`, local variables and objects such as `@order` contain?
+- Was the Active Record pool exhausted?
+- Was Puma out of thread capacity or building a backlog?
+- Were jobs failing or queues growing?
+- Was the process under GC, memory, descriptor or system pressure?
+- Which SQL queries, cache operations or Rails events preceded the failure?
+- Did a deploy introduce the error?
+- Can the failing request become a cURL reproduction or RSpec regression-test scaffold?
+
+## What makes RED different
+
+### Failure-time Ruby state
+
+Optionally capture local variables and — something no other error tracker does — the raising receiver's instance variables at `TracePoint(:raise)`, with bounded serialization and your Rails `filter_parameters` applied to sensitive values. Binding objects are never retained.
+
+### Failure-time Rails health
+
+Attach connection-pool, Puma, background-job, GC, memory, file-descriptor, TCP, RubyVM and YJIT state to the error record, refreshed on every captured occurrence — not merely to a separate periodic metrics chart. Every APM has these as time-series; none attaches them to the error. Opt-in; the procfs-backed fields are Linux-only.
+
+### Monitoring that degrades safely
+
+During an error flood, RED progressively reduces captured context and database work, keeps a fresh exemplar every minute, records the storm in a Storm History ledger and reconciles exact in-process occurrence counts onto the error records. On by default.
 
-### Try the Live Demo
+### Rails-specific investigation
 
-**[rails-error-dashboard.anjan.dev](https://rails-error-dashboard.anjan.dev)** — Username: `gandalf` · Password: `youshallnotpass`
+Connect exceptions with SQL, caching, Active Job, Action Cable, Active Storage, Rack::Attack, deprecations and other Rails subsystems from one dashboard.
 
-> **Beta Software** — Functional and tested (2,700+ tests passing), but the API may change before v1.0. Supports Rails 7.0-8.1 and Ruby 3.2-4.0.
+### Things no other tracker does
+
+Verified against Sentry, Honeybadger, AppSignal, Rollbar, Bugsnag, Airbrake, Raygun, New Relic, Datadog, Scout, Skylight and every self-hosted Rails tracker in August 2026 ([the ledger](.shipkit/research/red-unique-features-verified.md)):
+
+- **Copy as RSpec** — a runnable request spec generated from the captured request (Sentry offers curl only).
+- **Swallowed-exception aggregate** — raise-vs-rescue ratio per location, no APM span needed (Datadog's paid APM detects rescued exceptions but keeps no aggregate).
+- **Rack::Attack ledger** — throttle, blocklist and track events persisted with per-rule stats and an AI-crawler classifier; rack-attack ships no UI of its own.
+- **Codeberg issue tracking**, alongside GitHub, GitLab and Linear with two-way sync.
+- **The tracker instruments itself** — its capture pipeline exported as OpenTelemetry spans, so you can audit its overhead in your own APM.
+
+## How RED compares
+
+| Basic embedded tracker | General SaaS monitoring | RED |
+|---|---|---|
+| Stack trace and context | Cross-language telemetry and managed ingestion | Deep failure-time Ruby/Rails state inside the application boundary |
+| Lightweight and local | Strong distributed and frontend observability | Rails-specific operational investigation and storm-safe local capture |
+
+That makes RED a self-hosted Sentry alternative for teams that want Rails-specific depth and need error data to stay inside the application boundary — not a replacement for cross-language telemetry. RED has no mobile SDKs, no merge/split, no MCP server and no hosted operations.
+
+## Choose how you run it
+
+- Store data in the application's existing PostgreSQL, MySQL/Trilogy or SQLite database.
+- Isolate monitoring writes in a separate error database.
+- Use synchronous writes, or async logging through Sidekiq or Solid Queue (GoodJob is detected for job-health stats but is not an async adapter).
+- Track several Rails applications through a shared database.
+
+No RED licence or event-ingestion fee, and no plan limits — your database is the only cap, and storm protection deliberately sheds context during floods.
+
+---
 
 ### Screenshots
 
-**Dashboard Overview** — Real-time error stats, severity breakdown, and trend charts.
+**Dashboard Overview** — Live error stats, severity breakdown, and trend charts.
 
 ![Dashboard Overview](docs/images/dashboard-overview.png)
 
@@ -49,25 +122,12 @@ gem 'rails_error_dashboard'
 
 ---
 
-## Who This Is For
+## Safety, performance and compatibility
 
-- **Solo bootstrappers** who need professional error tracking without recurring costs
-- **Indie SaaS founders** building profitable apps on tight budgets
-- **Small dev teams** (2-5 people) who hate SaaS bloat
-- **Privacy-conscious apps** that need to keep error data on their own servers
-- **Side projects** that might become real businesses
-
-## What It Replaces
-
-| Before | After |
-|--------|-------|
-| $29-99/month for error monitoring | $0/month — runs on your existing Rails server |
-| Sensitive error data sent to third parties | All data stays on your infrastructure |
-| SaaS pricing tiers and usage limits | Unlimited errors, unlimited projects |
-| Vendor lock-in with proprietary APIs | 100% open source, fully portable |
-| Complex SDK setup and external services | 5-minute Rails Engine installation |
-| Pay extra for local variable capture (Sentry) | Local + instance variables included free |
-| No tool detects silently rescued exceptions | Swallowed exception detection built in |
+- **Host-app safety** — nothing in the capture path raises into your app; every subscriber and callback is rescue-wrapped, `Thread.current` is cleaned up in `ensure`, and the original exception is always re-raised. Variables, health and breadcrumbs are opt-in and off by default; storm protection is on by default and fails open.
+- **Performance** — the storm-protection hot path is a digest plus an atomic increment with no I/O; the figures quoted below are a maintainer's single-machine measurements and no benchmark script ships with the gem yet.
+- **Security** — HTTP Basic Auth or your own `authenticate_with` lambda (Devise, Warden, session); your Rails `filter_parameters` are applied to params, variables and breadcrumbs; prompts are never recorded by LLM observability. Vulnerability reports: [SECURITY.md](SECURITY.md).
+- **Compatibility** — Rails 7.0–8.1, Ruby 3.2–4.0, PostgreSQL, MySQL/Trilogy or SQLite; `turbo-rails` plus ActionCable are needed for live updates (no polling fallback); the gem's own CSS/JS is inline but Bootstrap JS, Chart.js, highlight.js and Google Fonts load from CDNs, so it is not air-gap clean.
 
 ---
 
@@ -75,14 +135,14 @@ gem 'rails_error_dashboard'
 
 ### Core (Always Enabled)
 
-Error capture from controllers, jobs, and middleware. Custom-designed dashboard with dark/light mode, search, filtering, and real-time updates. Analytics with trend charts, severity breakdown, and spike detection. Workflow management with assignment, priority, snooze, mute/unmute (notification suppression), comments, and batch operations. Security via HTTP Basic Auth or custom lambda (Devise, Warden, session-based). Exception cause chains, enriched HTTP context, custom fingerprinting, CurrentAttributes integration, auto-reopen on recurrence, and sensitive data filtering — all built in.
+Error capture from controllers, jobs, and middleware. Custom-designed dashboard with dark/light mode, search, filtering, and real-time updates (the latter with `turbo-rails` + ActionCable in the host). Analytics with trend charts, severity breakdown, and spike detection. Workflow management with assignment, priority, snooze, mute/unmute (notification suppression), comments, and batch operations. Security via HTTP Basic Auth or custom lambda (Devise, Warden, session-based). Exception cause chains, enriched HTTP context, custom fingerprinting, CurrentAttributes integration, auto-reopen on recurrence, and sensitive data filtering — all built in.
 
 ### Optional Features
 
 <details>
 <summary><strong>Storm Protection — Circuit Breaker + Adaptive Sampling</strong></summary>
 
-When the error rate spikes (a bad deploy throwing thousands of errors a minute), the nightmare scenario for any in-process tracker is amplifying the outage with its own database writes. Storm protection makes the gem **provably degrade itself first** — ON by default.
+When the error rate spikes (a bad deploy throwing thousands of errors a minute), the nightmare scenario for any in-process tracker is amplifying the outage with its own database writes. Storm protection is designed to **shed the gem's own expensive work first** — ON by default. The behaviour is measured (see Overhead below), though a bundled, reproducible benchmark is still to come.
 
 - **Per-fingerprint caps:** past N occurrences/minute per error, context is shed, then rows are sampled deterministically (a fresh exemplar is always kept each minute)
 - **Global circuit breaker:** sustained floods flip the gem to count-only mode — zero per-event I/O, exact in-memory counts reconciled onto error records every 30s. Async mode is gated too (a SolidQueue enqueue is itself a DB write)
@@ -98,7 +158,7 @@ config.storm_open_threshold_per_second = 50  # per process
 
 All thresholds are per process and individually configurable. Disable with one flag.
 
-**Measured overhead** (Apple Silicon, Ruby 4.0): 2.4µs/error with protection active and calm, 2.95µs in count-only mode, 0.2µs when disabled — against a 5µs budget. The check is a digest plus an atomic increment; there is no I/O on the hot path.
+**Overhead:** the check is a digest plus an atomic increment; there is no I/O on the hot path. The maintainer's single-machine measurement (Apple Silicon, Ruby 4.0) was 2.4µs/error with protection active and calm, 2.95µs in count-only mode and 0.2µs when disabled, against a 5µs budget — a reproducible benchmark script is not yet part of the gem.
 </details>
 
 <details>
@@ -108,7 +168,7 @@ See exactly what happened before the crash — SQL queries, controller actions,
 
 - Automatic capture — zero config beyond the enable flag
 - N+1 query detection with aggregate patterns page
-- Deprecation warnings with aggregate view
+- Deprecation warnings with aggregate view (needs the host's deprecation behaviour to include `:notify`; only requests that later raised are seen)
 - Custom breadcrumbs via `RailsErrorDashboard.add_breadcrumb("checkout started", { cart_id: 123 })`
 - Safe by design — fixed-size ring buffer, thread-local, every subscriber wrapped in rescue
 
@@ -146,7 +206,7 @@ Cross-error N+1 detection grouped by SQL fingerprint, and aggregate deprecation
 
 ![N+1 Query Patterns](docs/images/n-plus-one-queries.png)
 
-Requires breadcrumbs to be enabled.
+Requires breadcrumbs to be enabled. Deprecations are seen only when the host's `ActiveSupport::Deprecation` behaviour includes `:notify` (the production default does not) and only inside requests that later raised.
 
 [Complete documentation →](docs/FEATURES.md#n1-query-detection)
 </details>
@@ -154,7 +214,7 @@ Requires breadcrumbs to be enabled.
 <details>
 <summary><strong>Operational Health Panels — Jobs, Database, Cache, ActionCable</strong></summary>
 
-**Job Health** — Auto-detects Sidekiq, SolidQueue, or GoodJob. Per-error table with adapter badge, failed count (color-coded), sorted worst-first.
+**Job Health** — Aggregates the queue stats captured on each error (Sidekiq, SolidQueue or GoodJob auto-detected; needs `enable_system_health`). Not a live queue view — a per-error table with adapter badge, failed count (color-coded), sorted worst-first.
 
 ![Job Health](docs/images/job-health.png)
 
@@ -184,12 +244,12 @@ config.enable_activestorage_tracking = true  # requires enable_breadcrumbs = tru
 <details>
 <summary><strong>LLM Observability — Calls, Tokens, Cost, Tool Use</strong></summary>
 
-Capture every LLM call your app makes — model, latency, token counts, estimated USD cost, and tool-use requests — as breadcrumbs on the error that follows. When a request crashes, you see the chat completion that preceded it: which model was called, how long it took, what it cost, and which tools it asked to invoke.
+Capture your app's LLM calls — through a Faraday middleware, OpenTelemetry GenAI spans or a manual notification; nothing is auto-instrumented — as breadcrumbs on the error that follows, with model, latency, token counts, estimated USD cost and tool-use requests. When a request crashes, you see the chat completion that preceded it: which model was called, how long it took, what it cost, and which tools it asked to invoke.
 
 - Three capture paths — pick whichever matches your stack
 - Cost estimated from a built-in pricing table (Claude 4.x, GPT-4o/o1, Gemini 2.5) — override per-model via `config.llm_pricing_overrides`
 - Tool-call requests summarized inline; tool *execution* spans captured separately via the OTel path
-- Content capture (prompts/completions) **OFF by default** — only token counts and metadata are recorded
+- Prompts and completions are **never recorded** — only token counts and metadata (the `llm_observability_content_capture` flag is reserved and currently a no-op)
 - Same host-app safety guarantees as the rest of the gem — never raises, never blocks the request, every callback rescue-wrapped
 
 ```ruby
@@ -343,7 +403,7 @@ config.enable_git_blame = true
 <details>
 <summary><strong>Code Path Coverage (Diagnostic Mode)</strong></summary>
 
-Enable coverage via a dashboard button to see which production code paths were executed. Source code viewer overlays green checkmarks on executed lines and gray dots on unexecuted lines. Uses Ruby's `Coverage.setup(oneshot_lines: true)` — near-zero overhead, each line fires once. Zero overhead when off.
+Enable coverage via a dashboard button to see which production code paths were executed. Source code viewer overlays green checkmarks on executed lines and gray dots on unexecuted lines. Uses Ruby's `Coverage.setup(oneshot_lines: true)` — near-zero overhead, each line fires once. Zero overhead when off. Diagnostic mode only: coverage is process-global (a multi-threaded Puma blends requests), held in memory and not persisted. No error tracker integrates this; Coverband does it standalone with persistence.
 
 ```ruby
 config.enable_coverage_tracking = true   # shows Enable/Disable buttons on error detail page
@@ -372,7 +432,7 @@ config.llm_model = "gpt-5"
 <details>
 <summary><strong>Notifications — Slack, Discord, PagerDuty, Email, Webhooks</strong></summary>
 
-Multi-channel alerting with severity filters, per-error cooldown, and milestone threshold alerts to prevent alert fatigue.
+Multi-channel alerting with severity filters, per-error cooldown, milestone threshold alerts, and a per-environment allowlist (`config.notification_environments = %w[production]`) so a staging deploy never pages anyone.
 
 ```ruby
 config.enable_slack_notifications = true
@@ -382,6 +442,19 @@ config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
 [Notification setup guide →](docs/guides/NOTIFICATIONS.md)
 </details>
 
+<details>
+<summary><strong>Environment Awareness — Filter, Badge, Notify per Environment</strong></summary>
+
+Every error records the environment it came from — `production`, `staging`, `uat`, `preprod`, any name your deploys use. The errors index filters by it, rows and the detail page carry a badge, the analytics page breaks errors down by environment, and every notification names it. The same error in staging and production is two rows with independent status, so resolving one never hides the other.
+
+```ruby
+config.environment = ENV.fetch("ERROR_DASHBOARD_ENVIRONMENT", Rails.env)  # free-form, defaults to Rails.env
+config.notification_environments = %w[production]                         # nil = notify everywhere
+```
+
+Errors captured before v0.11.0 show no badge until they recur (the next occurrence claims the row) or you run `rails rails_error_dashboard:backfill_environments`.
+</details>
+
 <details>
 <summary><strong>Advanced Analytics</strong></summary>
 
@@ -392,9 +465,9 @@ Seven analysis engines built in:
 1. **Baseline Anomaly Alerts** — Statistical spike detection (mean + std dev) with intelligent cooldown
 2. **Fuzzy Error Matching** — Jaccard similarity + Levenshtein distance to find related errors
 3. **Co-occurring Errors** — Detect errors that happen together within configurable time windows
-4. **Error Cascade Detection** — Identify chains (A causes B causes C) with probability and delays
+4. **Error Cascade Detection** — Identify potential cascades (A is followed by B is followed by C) with probability and delays — temporal association, not proven causation
 5. **Error Correlation Analysis** — Correlate errors with app versions, git commits, and users
-6. **Platform Comparison** — iOS vs Android vs Web health metrics side-by-side
+6. **Platform Comparison** — iOS vs Android vs API health metrics side-by-side
 7. **Occurrence Pattern Detection** — Cyclical patterns (business hours, weekends) and burst detection
 
 [Complete documentation →](docs/FEATURES.md#advanced-analytics-features)
@@ -424,7 +497,7 @@ config.enable_instance_variables = true
 <details>
 <summary><strong>Swallowed Exception Detection</strong></summary>
 
-Detect exceptions that are raised but silently rescued — the hardest bugs to find. No other error tracker does this.
+Detect exceptions that are raised but silently rescued — the hardest bugs to find. Only Datadog's paid APM detects rescued exceptions (Ruby 3.3+, and only inside a traced request); RED does it free, without an APM span, and aggregates the raise-vs-rescue ratio per location — no other tracker does that.
 
 - Uses TracePoint(`:raise`) + TracePoint(`:rescue`) to track exception lifecycle
 - Identifies code paths where exceptions are caught but never logged or re-raised
@@ -465,7 +538,8 @@ config.enable_diagnostic_dump = true
 Track Rack Attack security events (throttles, blocklists, tracks) as breadcrumbs attached to errors, with a dedicated summary page.
 
 - Captures throttle, blocklist, and track events automatically
-- Dashboard page at `/errors/rack_attack_summary` with event breakdown
+- Dashboard page at `/errors/rack_attack_summary` with event breakdown and per-rule stats — rack-attack ships no UI of its own
+- Classifies AI-agent user agents (GPTBot, ClaudeBot, …) on `track` events
 - Requires breadcrumbs to be enabled
 
 ```ruby
@@ -483,7 +557,7 @@ Capture unhandled exceptions that crash the Ruby process via an `at_exit` hook
 - Disk-based fallback: writes crash data to disk because the database may be unavailable during shutdown
 - Imported automatically on next boot
 - Captures exception details, backtrace, uptime, GC stats, thread count, and cause chain
-- A self-hosted only feature — impossible for SaaS tools
+- Honeybadger, Bugsnag and AppSignal have `at_exit` reporters too; RED's writes to disk and imports at next boot because the database may already be gone during shutdown
 
 ```ruby
 config.enable_crash_capture = true
@@ -604,7 +678,7 @@ end
 
 ## Languages
 
-The dashboard, its emails and its notification payloads are translated. Eleven locales ship:
+RED ships in English with machine-translated previews for ten additional languages, covering the dashboard, its emails and its notification payloads. Native-speaking Rails developers are invited to review and improve them; once a locale has been reviewed it will be marked individually as community-reviewed. Eleven locales ship:
 
 | Locale | Language | Status |
 |---|---|---|
@@ -648,13 +722,13 @@ SQLite, PostgreSQL, and MySQL/Trilogy — in either shared or separate-database
 Yes. It runs entirely inside your own Rails process — no external services, no SDK calling out, no per-event pricing. Error data never leaves your infrastructure.
 
 **Does it capture local variables like Sentry?**
-Yes — local **and** instance variables at the moment the exception is raised, via `TracePoint(:raise)`, with sensitive-data filtering and configurable limits. This is opt-in and a capability Sentry charges extra for.
+Yes — local **and** instance variables at the moment the exception is raised, via `TracePoint(:raise)`, with sensitive-data filtering and configurable limits. It is opt-in. (Sentry's SDK can also capture locals as an opt-in option; RED adds instance variables and applies your Rails `filter_parameters` automatically.)
 
 **Will a flood of errors take down my app?**
-No. Storm protection (a circuit breaker with adaptive sampling, **ON by default**) makes the gem degrade itself first during error floods — occurrence counts stay exact while it sheds the expensive work. Measured hot-path overhead is ~2.4µs/error.
+No. Storm protection (a circuit breaker with adaptive sampling, **ON by default**) makes the gem degrade itself first during error floods — occurrence counts stay exact while it sheds the expensive work, and a Storm History page shows exactly what was shed. There is no I/O on the hot path — the check is a digest and an atomic increment.
 
 **Does it work with my background jobs?**
-Yes — it auto-detects and supports Sidekiq, SolidQueue, and GoodJob, and can log errors asynchronously through any of them.
+Yes — errors raised in jobs are captured, and it can log errors asynchronously through Sidekiq or SolidQueue (or the in-process `:async` adapter). Sidekiq, SolidQueue and GoodJob are all auto-detected for the job-queue stats stored on each error.
 
 **Does it work with my authentication?**
 Yes — HTTP Basic Auth out of the box, or a custom `authenticate_with` lambda that integrates with Devise, Warden, or session-based auth.
@@ -681,7 +755,7 @@ Rails 7.0–8.1 and Ruby 3.2–4.0.
 - **[Batch Operations](docs/guides/BATCH_OPERATIONS.md)** — Bulk resolve/delete
 - **[Real-Time Updates](docs/guides/REAL_TIME_UPDATES.md)** — Live dashboard
 - **[Error Trends](docs/guides/ERROR_TREND_VISUALIZATIONS.md)** — Charts and analytics
-- **[Translations](docs/guides/TRANSLATIONS.md)** — Seven shipped locales, correcting a string, adding a language
+- **[Translations](docs/guides/TRANSLATIONS.md)** — Eleven shipped locales, correcting a string, adding a language
 
 ### Advanced
 - **[Multi-App Support](docs/MULTI_APP_PERFORMANCE.md)** — Track multiple applications
@@ -690,7 +764,7 @@ Rails 7.0–8.1 and Ruby 3.2–4.0.
 - **[Customization](docs/CUSTOMIZATION.md)** — Customize everything
 - **[Database Options](docs/guides/DATABASE_OPTIONS.md)** — Separate database setup
 - **[Database Optimization](docs/guides/DATABASE_OPTIMIZATION.md)** — Performance tuning
-- **[Mobile App Integration](docs/guides/MOBILE_APP_INTEGRATION.md)** — React Native, Flutter, etc.
+- **[Mobile App Integration](docs/guides/MOBILE_APP_INTEGRATION.md)** — log mobile-originated errors through your own API endpoint, tagged by platform
 - **[FAQ](docs/FAQ.md)** — Common questions answered
 
 [View all documentation →](docs/README.md)
@@ -709,7 +783,7 @@ Built with **CQRS (Command/Query Responsibility Segregation)**:
 
 ## Testing
 
-2,600+ tests covering unit, integration, and browser-based system tests.
+An RSpec suite of unit, request and browser-based system specs runs in CI on every supported Rails version (see the Tests badge above); the current count lives in the CI log rather than here, where it would go stale.
 
 ```bash
 bundle exec rspec                              # Full suite

data/app/controllers/rails_error_dashboard/errors_controller.rb

@@ -11,6 +11,7 @@ module RailsErrorDashboard
       error_type
       unresolved
       platform
+      environment
       application_id
       search
       severity
@@ -94,6 +95,7 @@ module RailsErrorDashboard
       filter_options = Queries::FilterOptions.call(application_id: @current_application_id)
       @error_types = filter_options[:error_types]
       @platforms = filter_options[:platforms]
+      @environments = filter_options[:environments]
       @assignees = filter_options[:assignees]
     end
 
@@ -242,6 +244,7 @@ module RailsErrorDashboard
       @errors_over_time = analytics[:errors_over_time]
       @errors_by_type = analytics[:errors_by_type]
       @errors_by_platform = analytics[:errors_by_platform]
+      @errors_by_environment = analytics[:errors_by_environment]
       @errors_by_hour = analytics[:errors_by_hour]
       @top_users = analytics[:top_users]
       @resolution_rate = analytics[:resolution_rate]

data/app/mailers/rails_error_dashboard/error_notification_mailer.rb

@@ -20,12 +20,19 @@ module RailsErrorDashboard
     # The subject is assembled from a key rather than interpolated inline, so a
     # locale can reorder or drop the emoji. error_type and message are verbatim
     # error content and are never translated.
+    #
+    # An error that carries an environment uses subject_with_environment; a
+    # legacy row keeps the pre-0.11 subject so existing mail filters still match.
     def subject_for(error_log, locale)
+      environment = error_log.respond_to?(:environment) ? error_log.environment : nil
+      key = environment.present? ? "red.mailers.error_alert.subject_with_environment" : "red.mailers.error_alert.subject"
+
       I18nStore.translate(
-        "red.mailers.error_alert.subject",
+        key,
         locale: locale,
         application: error_log.application&.name ||
           I18nStore.translate("red.mailers.shared.unknown_application", locale: locale),
+        environment: environment,
         error_type: error_log.error_type,
         message: truncate_subject(error_log.message)
       )

data/app/models/rails_error_dashboard/error_log.rb

@@ -61,6 +61,7 @@ module RailsErrorDashboard
     scope :by_error_type, ->(type) { where(error_type: type) }
     scope :by_type, ->(type) { where(error_type: type) }
     scope :by_platform, ->(platform) { where(platform: platform) }
+    scope :by_environment, ->(environment) { where(environment: environment) }
     scope :last_24_hours, -> { where("occurred_at >= ?", 24.hours.ago) }
     scope :last_week, -> { where("occurred_at >= ?", 1.week.ago) }
 

data/app/views/layouts/rails_error_dashboard.html.erb

@@ -660,7 +660,16 @@ dd { color: var(--text-primary); }
   height: 48px; flex-shrink: 0;
   background: var(--surface-primary);
   border-bottom: 1px solid var(--border-primary);
+  /* A flex item's default min-width is auto, meaning "never shrink below my
+     content". Both navbar groups therefore kept their full intrinsic width on a
+     narrow screen and pushed the right-hand controls past the viewport — the
+     dashboard scrolled sideways at 375px in EVERY locale, English included.
+     min-width:0 lets them shrink; overflow:hidden keeps whatever still cannot
+     fit from extending the page rather than being clipped inside the bar. */
+  min-width: 0;
+  overflow: hidden;
 }
+.red-navbar > * { min-width: 0; }
 .red-search-input {
   width: 240px; padding: 5px 10px 5px 30px; font-size: 13px;
   border: 1px solid var(--border-primary); border-radius: var(--radius-sm);
@@ -720,6 +729,21 @@ dd { color: var(--text-primary); }
   .red-sidebar.collapsed { display: none; }
 }
 
+/* Stat grids
+   These were inline `grid-template-columns: repeat(N, 1fr)`, which cannot carry
+   a media query, so three or four cards stayed side by side at 375px and pushed
+   the page to 488px — it scrolled sideways on a phone in EVERY locale, English
+   worst of all. auto-fit + minmax lets the row reflow to two columns and then
+   one, and minmax's 0 floor stops a long word forcing a track wider than the
+   screen. */
+.red-stat-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(220px, 100%), 1fr));
+  gap: var(--space-4);
+  margin-bottom: var(--space-6);
+}
+.red-stat-grid > * { min-width: 0; }
+
 /* Error detail responsive grid */
 .red-detail-grid { display: grid; grid-template-columns: 1fr 260px; gap: var(--space-4); }
 @media (max-width: 1023.98px) { .red-detail-grid { grid-template-columns: 1fr; } }
@@ -729,7 +753,13 @@ dd { color: var(--text-primary); }
   padding: 3px 10px; font-size: 11px; font-weight: 600;
   border-radius: var(--radius-full);
   text-transform: uppercase; letter-spacing: 0.05em;
+  white-space: nowrap;
 }
+/* Below the sidebar breakpoint the navbar has to fit a menu button, search,
+   language picker, shortcuts, theme toggle and the env badge. The badge is
+   decoration — the environment is also on the overview page — so it is the
+   first thing dropped rather than letting it push the page sideways. */
+@media (max-width: 575.98px) { .red-env-badge { display: none; } }
 
 /* Kbd shortcut */
 kbd {

data/app/views/rails_error_dashboard/error_notification_mailer/error_alert.html.erb

@@ -148,6 +148,11 @@
           </div>
         <% end %>
 
+        <% if @error_log.respond_to?(:environment) && @error_log.environment.present? %>
+          <div class="label"><%= red_t("red.mailers.error_alert.labels.environment") %>:</div>
+          <div class="value"><strong><%= @error_log.environment %></strong></div>
+        <% end %>
+
         <div class="label"><%= red_t("red.mailers.error_alert.labels.occurred_at") %>:</div>
         <div class="value"><%= red_mail_time(@error_log.occurred_at) %></div>
 

data/app/views/rails_error_dashboard/error_notification_mailer/error_alert.text.erb

@@ -10,6 +10,7 @@
 <%= red_mail_t("red.mailers.error_alert.labels.application") %>: <%= @error_log.application&.name || red_mail_t("red.mailers.shared.unknown_application") %>
 <%= red_mail_t("red.mailers.error_alert.labels.error_type") %>: <%= @error_log.error_type %>
 <% if @error_log.platform.present? %><%= red_mail_t("red.mailers.error_alert.labels.platform") %>: <%= @error_log.platform %><% end %>
+<% if @error_log.respond_to?(:environment) && @error_log.environment.present? %><%= red_mail_t("red.mailers.error_alert.labels.environment") %>: <%= @error_log.environment %><% end %>
 <%= red_mail_t("red.mailers.error_alert.labels.occurred_at") %>: <%= red_mail_time(@error_log.occurred_at) %>
 <% if @error_log.user_id.present? %><%= red_mail_t("red.mailers.error_alert.labels.user_id") %>: <%= @error_log.user_id %><% end %>
 <% if @error_log.ip_address.present? %><%= red_mail_t("red.mailers.error_alert.labels.ip_address") %>: <%= @error_log.ip_address %><% end %>

data/app/views/rails_error_dashboard/errors/_error_row.html.erb

@@ -99,4 +99,12 @@
       <% end %>
     </td>
   <% end %>
+  <% if local_assigns[:show_environment] %>
+    <%# Environment names are free-form data (production, staging, uat...) and are never translated. %>
+    <td style="padding: var(--space-3) var(--space-4); font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;" title="<%= error.environment %>">
+      <% if error.environment.present? %>
+        <span class="badge badge-api" data-environment-badge="<%= error.environment %>"><i class="bi bi-hdd-stack"></i> <%= error.environment %></span>
+      <% end %>
+    </td>
+  <% end %>
 </tr>

data/app/views/rails_error_dashboard/errors/_sidebar_metadata.html.erb

@@ -70,6 +70,15 @@
             <% end %>
           </div>
 
+          <% if error.respond_to?(:environment) && error.environment.present? %>
+            <div class="mb-3">
+              <small class="metadata-label d-block mb-1"><%= red_t("red.errors.sidebar.environment") %></small>
+              <%= link_to errors_path(environment: error.environment, unresolved: '0'), class: "text-decoration-none", title: red_t("red.errors.sidebar.view_all_environment", environment: error.environment) do %>
+                <span class="badge badge-api" data-environment-badge="<%= error.environment %>"><i class="bi bi-hdd-stack"></i> <%= error.environment %></span>
+              <% end %>
+            </div>
+          <% end %>
+
           <div class="mb-3">
             <small class="metadata-label d-block mb-1"><%= red_t("red.errors.sidebar.user") %></small>
             <% if error.respond_to?(:user) && error.user %>

data/app/views/rails_error_dashboard/errors/analytics.html.erb

@@ -45,7 +45,7 @@
   </div>
 
   <!-- Summary Stats -->
-  <div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--space-4); margin-bottom: var(--space-6);">
+  <div class="red-stat-grid">
     <div class="card stat-card" style="border-left: 3px solid var(--accent); padding: var(--space-5) var(--space-6);">
       <div class="stat-label" style="margin-bottom: 4px;"><%= red_t("red.analytics.overview.stats.total_errors") %></div>
       <span class="stat-value"><%= @error_stats[:total] %></span>
@@ -155,6 +155,56 @@
     </div>
   <% end %>
 
+  <%# Errors by environment: same shape as the platform chart, shown only when
+      there is something to compare. Environment names are data, not text to
+      translate; NULL rows (captured before the column existed) are :unknown. %>
+  <% environment_counts = (@errors_by_environment || {}).transform_keys { |env| env == :unknown ? red_t("red.analytics.overview.environment_chart.unknown") : env } %>
+  <% if environment_counts.size > 1 %>
+    <div class="row g-4 mb-4">
+      <div class="col-md-12">
+        <div class="card">
+          <div class="card-header">
+            <h5 class="mb-0"><i class="bi bi-hdd-stack"></i> <%= red_t("red.analytics.overview.environment_chart.title") %></h5>
+          </div>
+          <div class="card-body">
+            <div id="errors-by-environment-chart"></div>
+            <script<%= " nonce=\"#{red_csp_nonce}\"".html_safe if red_csp_nonce %>>
+              document.addEventListener('DOMContentLoaded', function() {
+                const colors = window.getChartColors();
+                const environmentColors = ["#EF4444", "#F59E0B", "#2563EB", "#10B981", "#8B5CF6", "#6B7280"];
+
+                new Chartkick.PieChart("errors-by-environment-chart", <%= raw environment_counts.to_json %>, {
+                  colors: environmentColors,
+                  height: "300px",
+                  legend: "bottom",
+                  donut: true,
+                  library: {
+                    plugins: {
+                      legend: {
+                        labels: {
+                          color: colors.textColor,
+                          font: { size: 12, weight: 'bold' }
+                        }
+                      }
+                    }
+                  }
+                });
+              });
+            </script>
+          </div>
+          <div class="card-footer border-top-0">
+            <div class="d-flex gap-2 flex-wrap">
+              <small class="text-muted me-2"><%= red_t("red.analytics.overview.environment_chart.quick_links") %></small>
+              <% (@errors_by_environment || {}).keys.reject { |env| env == :unknown }.each do |environment| %>
+                <%= link_to environment, errors_path(environment: environment, unresolved: '0'), class: "btn btn-sm btn-outline-secondary" %>
+              <% end %>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  <% end %>
+
   <!-- Charts Row 2 -->
   <div class="row g-4 mb-4">
     <div class="col-md-12">

data/app/views/rails_error_dashboard/errors/database_health_summary.html.erb

@@ -91,7 +91,7 @@
   <% if @live_health[:postgresql] %>
     <%# Summary cards for PostgreSQL %>
     <% total_db_size = (@host_tables + @gem_tables).sum { |t| t[:total_bytes] } %>
-    <div style="display: grid; grid-template-columns: repeat(4, 1fr); gap: var(--space-4); margin-bottom: var(--space-4);">
+    <div class="red-stat-grid" style="margin-bottom: var(--space-4);">
       <div class="card stat-card" style="padding: var(--space-4) var(--space-5); text-align: center;">
         <div class="stat-label" style="margin-bottom: 4px;"><%= red_t("red.health.database.summary.total_db_size") %></div>
         <div class="stat-value"><%= number_to_human_size(total_db_size) %></div>

data/app/views/rails_error_dashboard/errors/index.html.erb

@@ -157,6 +157,9 @@
       <% if @platforms.size > 1 %>
         <%= select_tag :platform, options_for_select([[red_t("red.errors.index.filters.all_platforms"), '']] + @platforms.map { |p| [p, p] }, params[:platform]), class: "form-select", style: "width: auto; min-width: 120px;" %>
       <% end %>
+      <% if @environments.size > 1 %>
+        <%= select_tag :environment, options_for_select([[red_t("red.errors.index.filters.all_environments"), '']] + @environments.map { |e| [e, e] }, params[:environment]), class: "form-select", style: "width: auto; min-width: 120px;" %>
+      <% end %>
       <%= select_tag :error_type, options_for_select([[red_t("red.errors.index.filters.all_types"), '']] + @error_types.map { |t| [t, t] }, params[:error_type]), class: "form-select", style: "width: auto; min-width: 120px;" %>
       <%
         # Built from the same keys the active chips read, so a label can never
@@ -217,6 +220,7 @@
       active_filters << { label: red_t("red.errors.index.filters.chips.application", value: app_name), param: :application_id } if app_name
     end
     active_filters << { label: red_t("red.errors.index.filters.chips.platform", value: params[:platform]), param: :platform } if params[:platform].present?
+    active_filters << { label: red_t("red.errors.index.filters.chips.environment", value: params[:environment]), param: :environment } if params[:environment].present?
     active_filters << { label: red_t("red.errors.index.filters.chips.error_type", value: params[:error_type]), param: :error_type } if params[:error_type].present?
     active_filters << { label: red_t("red.errors.index.filters.chips.severity", value: severity_label.call(params[:severity])), param: :severity } if params[:severity].present?
     active_filters << { label: red_t("red.errors.index.filters.chips.timeframe", value: timeframe_label.call(params[:timeframe])), param: :timeframe } if params[:timeframe].present?
@@ -287,11 +291,14 @@
               <% if @platforms.size > 1 %>
                 <th style="padding: var(--space-3) var(--space-4); width: 100px;"><%= red_t("red.errors.index.columns.platform") %></th>
               <% end %>
+              <% if @environments.size > 1 %>
+                <th style="padding: var(--space-3) var(--space-4); width: 110px;"><%= red_t("red.errors.index.columns.environment") %></th>
+              <% end %>
             </tr>
           </thead>
           <tbody id="error_list">
             <% @errors.each do |error| %>
-              <%= render "error_row", error: error, show_platform: @platforms.size > 1, show_application: (@applications.size > 1 && params[:application_id].blank?) %>
+              <%= render "error_row", error: error, show_platform: @platforms.size > 1, show_environment: @environments.size > 1, show_application: (@applications.size > 1 && params[:application_id].blank?) %>
             <% end %>
           </tbody>
         </table>