Rails Informant

Self-hosted error monitoring for Rails, built for AI agents

Why Rails Informant? ◆ Quick Start ◆ Configuration ◆ MCP Server ◆ Architecture ◆ Data and Privacy ◆ Security

Captures exceptions, stores them in your app's database with rich context (backtraces, breadcrumbs, request data), sends notifications, and exposes error data via a bundled MCP server -- so AI agents can query, triage, and fix production errors directly.

No dashboard. The agent is the interface.

• Agent-native -- 12 MCP tools let AI agents list, inspect, resolve, and fix errors without a browser. The /informant Claude Code skill provides a complete triage-to-fix workflow.
• Self-hosted -- Errors stay in your database. No external service, no data leaving your infrastructure (unless you configure Slack or webhook notifications).
• Zero-config capture -- Errors captured automatically via Rails.error subscriber and Rack middleware. Breadcrumbs from ActiveSupport::Notifications provide structured debugging context.
• Lightweight -- Two database tables, no Redis, no background workers beyond ActiveJob. Runtime dependencies: Rails 8.1+ only.

Add to your Gemfile:

gem "rails-informant"

Install:

bundle install
bin/rails generate rails_informant:install
bin/rails db:migrate

Set an authentication token:

bin/rails credentials:edit

rails_informant:
  api_token: your-secret-token  # generate with: openssl rand -hex 32

Install Claude Code integration:

bin/rails generate rails_informant:skill

Errors are captured automatically in non-local environments. To capture errors manually:

RailsInformant.capture(exception, context: { order_id: 42 })

# config/initializers/rails_informant.rb
RailsInformant.configure do |config|
  config.capture_errors = !Rails.env.local?
  config.api_token = Rails.application.credentials.dig(:rails_informant, :api_token)
  config.slack_webhook_url = Rails.application.credentials.dig(:rails_informant, :slack_webhook_url)
  config.retention_days = 30
end

Every option can be set via an environment variable. The initializer takes precedence over env vars. These configure the Rails app. For MCP server env vars (agent side), see MCP Server > Setup.

Connecting the tokens: The api_token in your Rails credentials and INFORMANT_PRODUCTION_TOKEN must be the same value. The first authenticates incoming requests to your app; the second tells the MCP server what token to send.

Secrets hygiene: .envrc contains secrets and should be in .gitignore. .mcp.json is safe to commit -- it only contains the command name, no tokens.

Errors are captured automatically via:

1. Rails.error subscriber -- background jobs, mailer errors, Rails.error.handle blocks
2. Rack middleware -- unhandled request exceptions and rescued framework exceptions

Errors are grouped by SHA256(class_name:first_app_backtrace_frame). Line numbers are normalized so the same error at different lines groups together.

Common framework exceptions (404s, CSRF, etc.) are ignored by default. Add more:

config.ignored_exceptions = ["MyApp::BoringError", /Stripe::/]

Structured events from ActiveSupport::Notifications are captured automatically as breadcrumbs -- SQL query names, cache hits, template renders, HTTP calls, job executions. Stored per-occurrence for rich debugging context without raw log lines.

The bundled informant-mcp executable connects Claude Code to your error data via Model Context Protocol (MCP).

The rails_informant:skill generator creates .mcp.json automatically. Set INFORMANT_PRODUCTION_URL and INFORMANT_PRODUCTION_TOKEN as environment variables (e.g., via .envrc + direnv). The MCP server inherits env vars from your shell.

For multi-environment setups, create ~/.config/informant-mcp.yml:

environments:
  production:
    url: https://myapp.com
    token: ${INFORMANT_PRODUCTION_TOKEN}
  staging:
    url: https://staging.myapp.com
    token: ${INFORMANT_STAGING_TOKEN}

The MCP server enforces HTTPS by default. When pointing at a local HTTP URL (e.g., http://localhost:3000), pass --allow-insecure:

{
  "mcpServers": {
    "informant": {
      "command": "informant-mcp",
      "args": ["--allow-insecure"]
    }
  }
}

This is only needed for local development/testing. Production setups over HTTPS don't need it.

Use /informant in Claude Code to triage and fix errors interactively. The skill:

1. Checks error status with get_informant_status
2. Lists unresolved errors
3. Investigates with full occurrence data
4. Implements fixes with test-first workflow
5. Marks fix_pending for auto-resolution on deploy

Development Machine                    Remote Servers
+-----------------------+              +-----------------------+
|  Claude Code          |              |  Production           |
|        |              |              |  /informant           |
|        | stdio        |              +-----------------------+
|        v              |  HTTPS+Token
|  MCP Server           | -----------> +-----------------------+
|  (exe/informant-mcp)  |              |  Staging              |
|                       |              |  /informant           |
+-----------------------+              +-----------------------+

Inside the Rails app:
+-------------------------------------------------+
|  Rails.error subscriber (primary capture)       |
|  Rack Middleware (safety net)                    |
|    - ErrorCapture (before ShowExceptions)        |
|    - RescuedExceptionInterceptor (after Debug)   |
|  |                                              |
|  v                                              |
|  Fingerprint + Upsert (atomic counter)          |
|  |                                              |
|  v                                              |
|  Occurrence.create (with breadcrumbs, context)  |
|  |                                              |
|  v                                              |
|  NotifyJob.perform_later (async dispatch)       |
|    - Slack (Block Kit, Net::HTTP)               |
|    - Webhook (PII stripped by default)          |
+-------------------------------------------------+

unresolved --> fix_pending --> resolved (auto, on deploy)
unresolved --> resolved (manual)
unresolved --> ignored
unresolved --> duplicate
resolved    --> unresolved [REGRESSION]
fix_pending --> unresolved (reopen)
ignored     --> unresolved (reopen)
duplicate   --> unresolved (reopen)

On boot, the engine checks if fix_pending errors have been deployed by comparing the current git SHA against original_sha. Deployed fixes are automatically transitioned to resolved.

Git SHA is resolved from environment variables (GIT_SHA, REVISION, KAMAL_VERSION) or .git/HEAD.

bin/rails informant:stats    # Show error monitoring statistics
bin/rails informant:purge    # Purge resolved errors older than retention_days

Each occurrence stores the following PII:

• User email -- only captured when config.capture_user_email = true and the user model responds to #email
• IP address -- from request.remote_ip
• Custom user context -- anything set via RailsInformant::Current.user_context

For GDPR compliance, only include identifiers needed for debugging (e.g., user ID) rather than personal data. You can override automatic user detection by setting user context explicitly:

# In a before_action or around_action
RailsInformant::Current.user_context = { id: current_user.id }

All stored context passes through ActiveSupport::ParameterFilter, so adding keys to filter_parameters suppresses them:

# config/application.rb
config.filter_parameters += [:email]

This replaces email values with [FILTERED] in occurrence data. IP addresses can be suppressed the same way by adding :ip.

• MCP server requires token authentication (secure_compare)
• All stored context is filtered through ActiveSupport::ParameterFilter
• MCP server enforces HTTPS by default
• Security headers: Cache-Control: no-store, X-Content-Type-Options: nosniff
• Error capture never breaks the host application
• Webhook payloads strip PII by default
• Rate limiting -- the engine does not include built-in rate limiting. Add rate limiting on the /informant/ prefix in production, for example with Rack::Attack:

# config/initializers/rack_attack.rb
Rack::Attack.throttle("informant", limit: 60, period: 1.minute) do |req|
  req.ip if req.path.start_with?("/informant/")
end

This project is licensed under the MIT License -- see the LICENSE file for details.