faultline

Faultline

A self-hosted error tracking engine for Rails 8+ applications. Track errors, get notified, and resolve issues—all without external services.

Features

• Automatic Error Capture - Rack middleware + Rails error reporting API
• Smart Grouping - Errors are grouped by fingerprint (class + message + location)
• Debugger Inspector - Side-by-side source code and local variables view, like a real debugger
• Local Variables Capture - Automatic capture of variable values at the raise point
• Full-Text Search - Search errors by exception class, message, or file path
• Status Management - Mark errors as resolved, unresolved, or ignored
• Auto-Reopen - Resolved errors automatically reopen when they recur
• GitHub Integration - Create GitHub issues directly from errors with full context
• Rate Limiting - Configurable cooldown prevents notification spam during error storms
• Pluggable Notifiers - Telegram, Slack, Discord, Email (ActionMailer or Resend), webhooks, or build your own
• Standalone Dashboard - Clean Tailwind UI with interactive charts and time-range zooming
• Configurable Authentication - Integrate with Devise, Warden, or custom auth
• Request Context - Capture URL, params, headers, user info, and custom data
• APM (Experimental) - Track response times, throughput, database query counts, span waterfall timelines, and CPU flame graphs per endpoint
• MCP Server - Built-in Model Context Protocol endpoint and Claude Code plugin so AI assistants can fetch error context (backtraces, locals, traces) directly while debugging

Requirements

• Ruby >= 3.2
• Rails >= 8.0
• PostgreSQL, MySQL, or SQLite

Installation

Add to your Gemfile:

gem "faultline", git: "https://github.com/dlt/faultline.git"

# Or from RubyGems (when published)
# gem "faultline"

Run the installer:

bundle install
rails generate faultline:install
rails db:migrate

Configuration

Edit config/initializers/faultline.rb:

Authentication (Required for Production)

Faultline.configure do |config|
  # Devise with admin role
  config.authenticate_with = lambda { |request|
    user = request.env["warden"]&.user
    user&.admin?
  }

  # Or any authenticated user
  config.authenticate_with = lambda { |request|
    request.env["warden"]&.authenticated?
  }
end

GitHub Integration

Create GitHub issues directly from the error dashboard with full context including stack traces, local variables, and source code snippets.

# Store in credentials: rails credentials:edit
# faultline:
#   github:
#     token: "ghp_xxxxx"

config.github_repo = "your-org/your-repo"
config.github_token = Rails.application.credentials.dig(:faultline, :github, :token)
config.github_labels = ["bug", "faultline"]  # default labels for created issues

Notifications (Optional)

Notifications are optional. Faultline will track all errors and display them in the dashboard regardless of whether any notifiers are configured. Add notifiers only if you want to be alerted when errors occur.

Resend (Email)

# Store in credentials: rails credentials:edit
# faultline:
#   resend:
#     api_key: "re_xxxxx"

config.add_notifier(
  Faultline::Notifiers::Resend.new(
    api_key: Rails.application.credentials.dig(:faultline, :resend, :api_key),
    from: "errors@yourdomain.com",
    to: "team@example.com"  # or array: ["dev@example.com", "ops@example.com"]
  )
)

Email (ActionMailer)

Use your app's existing mail configuration (SMTP, SendGrid, Postmark, Mailgun, etc.) without any external API:

config.add_notifier(
  Faultline::Notifiers::Email.new(
    to: ["team@example.com", "oncall@example.com"],
    from: "errors@yourdomain.com"  # optional, defaults to ActionMailer default
  )
)

Emails are sent asynchronously via deliver_later, so Active Job must be configured. The email includes:

• Exception class and message
• Occurrence count and timestamps
• File location and stack trace
• User and request info (if available)

Telegram

# Store in credentials: rails credentials:edit
# faultline:
#   telegram:
#     bot_token: "your-bot-token"
#     chat_id: "your-chat-id"
#     message_thread_id: 123 # optional, for forum topics

config.add_notifier(
  Faultline::Notifiers::Telegram.new(
    bot_token: Rails.application.credentials.dig(:faultline, :telegram, :bot_token),
    chat_id: Rails.application.credentials.dig(:faultline, :telegram, :chat_id),
    message_thread_id: Rails.application.credentials.dig(:faultline, :telegram, :message_thread_id)
  )
)

Slack