dontbugme 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb0afce7d9aa5e4a8f372a7b7b3b2e24ecfd3e5c7cb7e9c05afbb3dee2deb635
+  data.tar.gz: 462510e9da9e18d236a65a46e9c25a0b4c8ada876d059e5209b05c63d041bddb
+SHA512:
+  metadata.gz: '09be1265d9bd33cf45291cb52c7085e2c3f00f95de5f6a7e54f5dcd22522ecf9264413824aaa7d9c4b4eceef8a5edce099f294dfee0d94bc27661bb025e6c070'
+  data.tar.gz: e8690b9f9d2937f18751ba50903130e143dc6e4148808ca2f10dba299cf72ad28bbf021e4e9c0d1d247d51894a9c7692067da9165c69c14fea660f9e511aeac7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,174 @@
+# Dontbugme
+
+A flight recorder for Rails applications. Reconstruct the full execution story of Sidekiq jobs and HTTP requests — see exactly what database queries ran, what HTTP services were called, what exceptions were raised, with source locations pointing to your code.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'dontbugme'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Automatic Recording
+
+Dontbugme automatically records:
+
+- **Sidekiq jobs** — via Sidekiq server middleware
+- **HTTP requests** — via Rack middleware
+- **SQL queries** — via ActiveSupport::Notifications
+- **HTTP calls** — Net::HTTP (including Faraday, which uses it)
+- **Redis** — Redis gem operations
+- **Cache** — Rails cache read/write/delete
+- **Mailer** — ActionMailer deliveries
+- **Job enqueue** — Active Job enqueues
+
+In development, recording is on by default. Run your app normally, then inspect:
+
+```bash
+# List recent traces
+bundle exec dontbugme list
+
+# Show a specific trace
+bundle exec dontbugme show tr_abc123
+
+# Filter spans
+bundle exec dontbugme show tr_abc123 --only=sql
+bundle exec dontbugme show tr_abc123 --slow=10
+
+# JSON output
+bundle exec dontbugme show tr_abc123 --json
+```
+
+### Manual Tracing
+
+Wrap any block to capture a trace:
+
+```ruby
+trace = Dontbugme.trace("my debug session") do
+  User.find(42)
+  Order.where(user_id: 42).count
+end
+
+puts trace.to_timeline
+# Or: trace.spans, trace.status, trace.duration_ms
+```
+
+### Manual Spans and Snapshots
+
+Add custom spans and snapshots within a trace:
+
+```ruby
+trace = Dontbugme.trace("checkout flow") do
+  Dontbugme.span("Calculate tax") do
+    tax = order.calculate_tax
+  end
+  Dontbugme.snapshot(user: user.attributes.slice("id", "email"), total: order.total)
+  Dontbugme.tag(customer_tier: "enterprise")
+end
+```
+
+### Span Categories
+
+Access spans by category for assertions or analysis:
+
+```ruby
+trace.spans.sql        # SQL queries
+trace.spans.http       # HTTP calls
+trace.spans.redis      # Redis operations
+trace.spans.category(:mailer)  # Any category
+```
+
+### Search
+
+```bash
+bundle exec dontbugme search --status=error --class=SendInvoiceJob --limit=10
+```
+
+### Trace Diff
+
+Compare two executions to see what changed:
+
+```bash
+bundle exec dontbugme diff tr_success tr_failed
+```
+
+Shows IDENTICAL, CHANGED, MISSING, and NEW spans between the two traces.
+
+### Correlation Chain
+
+When a request enqueues jobs, they share a `correlation_id`. Follow the full chain:
+
+```bash
+bundle exec dontbugme trace tr_request_id --follow
+```
+
+Shows all traces (request + enqueued jobs) with the same correlation ID. Correlation IDs are automatically propagated from HTTP requests to Sidekiq jobs (and from job to child job) when using the Rails integration.
+
+### Web UI (optional)
+
+A lightweight web interface to browse traces. **Disabled by default in production.** Enable in development:
+
+```ruby
+# config/initializers/dontbugme.rb
+Dontbugme.configure do |config|
+  config.enable_web_ui = true  # default: true in dev, false in prod
+  config.web_ui_mount_path = '/inspector'
+end
+```
+
+Add to `config/routes.rb`:
+
+```ruby
+mount Dontbugme::Engine, at: '/inspector' if Dontbugme.config.enable_web_ui
+```
+
+Then visit `/inspector` to browse traces, search, and compare.
+
+### Configuration
+
+Create `config/initializers/dontbugme.rb`:
+
+```ruby
+Dontbugme.configure do |config|
+  config.store = :sqlite
+  config.sqlite_path = "tmp/inspector/inspector.db"
+  config.recording_mode = :always
+  config.capture_sql_binds = true
+  config.source_mode = :full
+end
+```
+
+## Storage
+
+- **SQLite** (default): Zero config. Data at `tmp/inspector/inspector.db`
+- **PostgreSQL**: Uses your Rails DB. Set `config.store = :postgresql`
+- **Memory**: For tests. Traces lost on process exit.
+
+## Cleanup
+
+Traces are ephemeral. Run cleanup to enforce retention:
+
+```ruby
+Dontbugme::CleanupJob.perform
+```
+
+Schedule via cron or Sidekiq to run periodically.
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 7.0 (for full integration)
+- Sidekiq >= 7.0 (optional, for job tracing)
+
+## License
+
+MIT

data/app/controllers/dontbugme/traces_controller.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Dontbugme
+  class TracesController < ActionController::Base
+    layout 'dontbugme/application'
+
+    before_action :ensure_enabled
+
+    def index
+      filters = { limit: 50 }
+      filters[:status] = params[:status] if params[:status].present?
+      filters[:kind] = params[:kind] if params[:kind].present?
+      filters[:identifier] = params[:q] if params[:q].present?
+      filters[:correlation_id] = params[:correlation_id] if params[:correlation_id].present?
+      @traces = store.search(filters)
+    end
+
+    def show
+      @trace = store.find_trace(params[:id])
+      return render plain: 'Trace not found', status: :not_found unless @trace
+    end
+
+    def diff
+      @trace_a = params[:a].present? ? store.find_trace(params[:a]) : nil
+      @trace_b = params[:b].present? ? store.find_trace(params[:b]) : nil
+      @diff_output = if @trace_a && @trace_b
+        Formatters::Diff.format(@trace_a, @trace_b)
+      else
+        nil
+      end
+    end
+
+    private
+
+    def store
+      Dontbugme.store
+    end
+
+    def ensure_enabled
+      return if Dontbugme.config.enable_web_ui
+
+      render plain: 'Dontbugme Web UI is disabled. Set config.enable_web_ui = true to enable.', status: :forbidden
+    end
+  end
+end

data/app/views/dontbugme/traces/diff.html.erb

@@ -0,0 +1,18 @@
+<%= form_with url: diff_path, method: :get, local: true, class: 'diff-form' do %>
+  <input type="text" name="a" value="<%= params[:a] %>" placeholder="Trace A ID (e.g. tr_abc123)">
+  <span>vs</span>
+  <input type="text" name="b" value="<%= params[:b] %>" placeholder="Trace B ID (e.g. tr_def456)">
+  <button type="submit">Compare</button>
+<% end %>
+
+<% if @diff_output %>
+  <div class="card">
+    <div class="diff-output"><%= @diff_output %></div>
+  </div>
+<% elsif params[:a].present? || params[:b].present? %>
+  <p class="empty">Enter two trace IDs to compare. Use the trace list to find IDs.</p>
+<% else %>
+  <p class="empty">Enter two trace IDs above to see what changed between two executions.</p>
+<% end %>
+
+<p style="margin-top: 16px;"><%= link_to '← Back to traces', root_path %></p>

data/app/views/dontbugme/traces/index.html.erb

@@ -0,0 +1,30 @@
+<%= form_with url: root_path, method: :get, local: true, class: 'filters' do |f| %>
+  <input type="text" name="q" value="<%= params[:q] %>" placeholder="Search identifier..." style="min-width: 200px;">
+  <select name="status">
+    <option value="">All statuses</option>
+    <option value="success" <%= params[:status] == 'success' ? 'selected' : '' %>>Success</option>
+    <option value="error" <%= params[:status] == 'error' ? 'selected' : '' %>>Error</option>
+  </select>
+  <select name="kind">
+    <option value="">All kinds</option>
+    <option value="sidekiq" <%= params[:kind] == 'sidekiq' ? 'selected' : '' %>>Sidekiq</option>
+    <option value="request" <%= params[:kind] == 'request' ? 'selected' : '' %>>Request</option>
+    <option value="custom" <%= params[:kind] == 'custom' ? 'selected' : '' %>>Custom</option>
+  </select>
+  <button type="submit">Filter</button>
+<% end %>
+
+<div class="card">
+  <% if @traces.any? %>
+    <% @traces.each do |trace| %>
+      <div class="trace-row">
+        <span class="trace-id"><%= link_to trace.id, trace_path(trace.id) %></span>
+        <span class="trace-identifier"><%= trace.identifier %></span>
+        <span class="badge <%= trace.status == :success ? 'badge-success' : 'badge-error' %>"><%= trace.status %></span>
+        <span class="trace-duration"><%= trace.duration_ms ? "#{trace.duration_ms.round}ms" : '-' %></span>
+      </div>
+    <% end %>
+  <% else %>
+    <p class="empty">No traces found. Run your app and execute some jobs or requests.</p>
+  <% end %>
+</div>

data/app/views/dontbugme/traces/show.html.erb

@@ -0,0 +1,15 @@
+<div class="card">
+  <h2 style="margin: 0 0 8px; font-size: 16px;"><%= @trace.identifier %></h2>
+  <p style="margin: 0 0 16px; color: #6b7280; font-size: 12px;">
+    <%= @trace.id %> · <%= @trace.status %> · <%= @trace.duration_ms ? "#{@trace.duration_ms.round}ms" : 'N/A' %>
+    <% if @trace.correlation_id.present? %>
+      · <%= link_to "Follow chain", root_path(correlation_id: @trace.correlation_id) %>
+    <% end %>
+  </p>
+  <div class="timeline"><%= Formatters::Timeline.format(@trace) %></div>
+</div>
+
+<p style="margin-top: 16px;">
+  <%= link_to '← Back to traces', root_path %> ·
+  <%= link_to 'Compare with another trace', diff_path(a: @trace.id) %>
+</p>

data/app/views/layouts/dontbugme/application.html.erb

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Dontbugme</title>
+  <style>
+    * { box-sizing: border-box; }
+    body { font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace; font-size: 13px; line-height: 1.5; color: #1a1a1a; background: #f8f9fa; margin: 0; padding: 0; }
+    .container { max-width: 1000px; margin: 0 auto; padding: 24px; }
+    header { background: #fff; border-bottom: 1px solid #e5e7eb; padding: 16px 24px; margin-bottom: 24px; }
+    header h1 { margin: 0; font-size: 18px; font-weight: 600; }
+    header nav { margin-top: 12px; }
+    header a { color: #4b5563; text-decoration: none; margin-right: 16px; }
+    header a:hover { color: #111; }
+    header a.active { color: #111; font-weight: 600; }
+    .card { background: #fff; border-radius: 6px; border: 1px solid #e5e7eb; padding: 16px; margin-bottom: 16px; }
+    .trace-row { display: flex; align-items: center; gap: 16px; padding: 0 0 12px; border-bottom: 1px solid #f3f4f6; }
+    .trace-row:last-child { border-bottom: none; padding-bottom: 0; }
+    .trace-row:hover { background: #f9fafb; margin: 0 -16px; padding: 0 16px 12px; }
+    .trace-id { font-family: monospace; font-size: 12px; color: #6b7280; min-width: 140px; }
+    .trace-id a { color: #2563eb; text-decoration: none; }
+    .trace-id a:hover { text-decoration: underline; }
+    .trace-identifier { flex: 1; }
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 11px; font-weight: 500; }
+    .badge-success { background: #d1fae5; color: #065f46; }
+    .badge-error { background: #fee2e2; color: #991b1b; }
+    .trace-duration { color: #6b7280; min-width: 50px; }
+    .filters { display: flex; gap: 12px; margin-bottom: 16px; flex-wrap: wrap; }
+    .filters input, .filters select { padding: 8px 12px; border: 1px solid #e5e7eb; border-radius: 4px; font-size: 13px; }
+    .filters button { padding: 8px 16px; background: #111; color: #fff; border: none; border-radius: 4px; cursor: pointer; font-size: 13px; }
+    .filters button:hover { background: #333; }
+    .timeline { font-size: 12px; white-space: pre-wrap; font-family: ui-monospace, monospace; }
+    .span-line { padding: 4px 0; }
+    .span-source { color: #6b7280; padding-left: 12px; font-size: 11px; }
+    .diff-form { display: flex; gap: 12px; align-items: center; margin-bottom: 24px; }
+    .diff-form input { flex: 1; padding: 8px 12px; border: 1px solid #e5e7eb; border-radius: 4px; }
+    .diff-output { white-space: pre-wrap; font-size: 12px; background: #1f2937; color: #e5e7eb; padding: 16px; border-radius: 6px; overflow-x: auto; }
+    .empty { color: #6b7280; padding: 24px; text-align: center; }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="container">
+      <h1>Dontbugme</h1>
+      <nav>
+        <%= link_to 'Traces', root_path, class: (controller_name == 'traces' && action_name == 'index' ? 'active' : '') %>
+        <%= link_to 'Diff', diff_path, class: (action_name == 'diff' ? 'active' : '') %>
+      </nav>
+    </div>
+  </header>
+  <main class="container">
+    <%= yield %>
+  </main>
+</body>
+</html>

data/bin/dontbugme

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'dontbugme'
+Dontbugme::CLI.start

data/lib/dontbugme/cleanup_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dontbugme
+  class CleanupJob
+    def self.perform
+      store = Dontbugme.store
+      return unless store
+
+      config = Dontbugme.config
+      retention = config.retention
+      return unless retention
+
+      cutoff = Time.now - retention
+      store.cleanup(before: cutoff)
+    end
+  end
+end

data/lib/dontbugme/cli.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Dontbugme
+  class CLI < Thor
+    desc 'list', 'List recent traces'
+    option :limit, type: :numeric, default: 20, aliases: '-n'
+    def list
+      ensure_loaded
+      traces = store.search(limit: options[:limit])
+      display_list(traces)
+    end
+
+    desc 'show TRACE_ID', 'Show a single trace'
+    option :only, type: :string, desc: 'Filter spans by category (sql, http, etc.)'
+    option :slow, type: :numeric, desc: 'Only show spans slower than N ms'
+    option :json, type: :boolean, default: false
+    def show(trace_id)
+      ensure_loaded
+      trace = store.find_trace(trace_id)
+      if trace.nil?
+        puts "Trace not found: #{trace_id}"
+        exit 1
+      end
+
+      if options[:json]
+        puts Formatters::Json.format(trace)
+      else
+        puts Formatters::Timeline.format(trace, only: options[:only], slow: options[:slow])
+      end
+    end
+
+    desc 'diff TRACE_A TRACE_B', 'Compare two traces'
+    def diff(trace_id_a, trace_id_b)
+      ensure_loaded
+      trace_a = store.find_trace(trace_id_a)
+      trace_b = store.find_trace(trace_id_b)
+      if trace_a.nil?
+        puts "Trace not found: #{trace_id_a}"
+        exit 1
+      end
+      if trace_b.nil?
+        puts "Trace not found: #{trace_id_b}"
+        exit 1
+      end
+      puts Formatters::Diff.format(trace_a, trace_b)
+    end
+
+    desc 'trace TRACE_ID', 'Show trace and follow correlation chain'
+    option :follow, type: :boolean, default: false, aliases: '-f'
+    def trace(trace_id)
+      ensure_loaded
+      root = store.find_trace(trace_id)
+      if root.nil?
+        puts "Trace not found: #{trace_id}"
+        exit 1
+      end
+
+      if options[:follow]
+        cid = root.correlation_id || root.metadata[:correlation_id]
+        if cid.nil? || cid.to_s.empty?
+          puts "No correlation ID for trace #{trace_id}. Showing single trace."
+          puts Formatters::Timeline.format(root)
+          return
+        end
+        traces = store.search(correlation_id: cid, limit: 100)
+        puts format_correlation_tree(traces, root)
+      else
+        puts Formatters::Timeline.format(root)
+      end
+    end
+
+    desc 'search', 'Search traces'
+    option :status, type: :string, desc: 'Filter by status (success, error)'
+    option :kind, type: :string, desc: 'Filter by kind (sidekiq, request, custom)'
+    option :identifier, type: :string, desc: 'Filter by identifier (partial match)'
+    option :class, type: :string, desc: 'Filter by job/request class (e.g. SendInvoiceJob)'
+    option :limit, type: :numeric, default: 20
+    def search
+      ensure_loaded
+      filters = { limit: options[:limit] }
+      filters[:status] = options[:status] if options[:status]
+      filters[:kind] = options[:kind] if options[:kind]
+      filters[:identifier] = options[:identifier] || options[:class]
+      traces = store.search(filters)
+      display_list(traces)
+    end
+
+    default_task :list
+
+    private
+
+    def ensure_loaded
+      # Gem is loaded by bin/dontbugme; this is a no-op when used as a gem
+      require 'dontbugme' unless defined?(Dontbugme)
+    end
+
+    def store
+      Dontbugme.store
+    end
+
+    def display_list(traces)
+      return puts('No traces found.') if traces.empty?
+
+      rows = traces.map do |trace|
+        [
+          trace.id,
+          truncate(trace.identifier, 24),
+          status_icon(trace.status),
+          duration_str(trace)
+        ]
+      end
+
+      # Simple table
+      col_widths = [12, 26, 6, 10]
+      puts ''
+      puts row_str(['Trace ID', 'Identifier', 'Status', 'Duration'], col_widths)
+      puts row_str(['-' * 12, '-' * 24, '-' * 4, '-' * 8], col_widths)
+      rows.each { |r| puts row_str(r, col_widths) }
+      puts ''
+    end
+
+    def row_str(cols, widths)
+      cols.each_with_index.map { |c, i| c.to_s.ljust(widths[i]) }.join('  ')
+    end
+
+    def truncate(str, max)
+      return str if str.length <= max
+
+      "#{str[0, max - 3]}..."
+    end
+
+    def status_icon(status)
+      status.to_s == 'success' ? '✓' : '✗'
+    end
+
+    def duration_str(trace)
+      ms = trace.duration_ms
+      ms ? "#{ms.round}ms" : '-'
+    end
+
+    def format_correlation_tree(traces, root)
+      lines = []
+      lines << ''
+      lines << "  Correlation: #{root.correlation_id || root.metadata[:correlation_id]}"
+      lines << '  ' + ('─' * 60)
+      lines << ''
+
+      # Order: request first, then jobs by started_at
+      sorted = traces.sort_by do |t|
+        kind_order = { request: 0, sidekiq: 1, custom: 2 }
+        [kind_order[t.kind] || 3, t.started_at_utc.to_s]
+      end
+
+      display_trace = lambda do |t|
+        icon = t.status == :success ? '✓' : '✗'
+        duration = t.duration_ms ? "#{t.duration_ms.round}ms" : '-'
+        "#{t.identifier} (#{t.id}, #{duration}, #{t.status})"
+      end
+
+      sorted.each_with_index do |t, i|
+        prefix = i.zero? ? '' : (i == sorted.size - 1 ? '└── ' : '├── ')
+        lines << "  #{prefix}#{display_trace.call(t)}"
+      end
+
+      lines << ''
+      lines.join("\n")
+    end
+  end
+end

data/lib/dontbugme/config/routes.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  root to: 'traces#index', as: :root
+  get 'diff', to: 'traces#diff', as: :diff
+  get ':id', to: 'traces#show', as: :trace, constraints: { id: /tr_[a-f0-9]+/ }
+end