dontbugme 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb0afce7d9aa5e4a8f372a7b7b3b2e24ecfd3e5c7cb7e9c05afbb3dee2deb635
-  data.tar.gz: 462510e9da9e18d236a65a46e9c25a0b4c8ada876d059e5209b05c63d041bddb
+  metadata.gz: f54f514d06627f29c5f89eecf392fd8c5df427acaa219a97ca70ca682274b2c0
+  data.tar.gz: 404c4e20b7f5c447bdc20d2460b2bdd2c788aba50e9b9069c3a5d0b62c4466a0
 SHA512:
-  metadata.gz: '09be1265d9bd33cf45291cb52c7085e2c3f00f95de5f6a7e54f5dcd22522ecf9264413824aaa7d9c4b4eceef8a5edce099f294dfee0d94bc27661bb025e6c070'
-  data.tar.gz: e8690b9f9d2937f18751ba50903130e143dc6e4148808ca2f10dba299cf72ad28bbf021e4e9c0d1d247d51894a9c7692067da9165c69c14fea660f9e511aeac7
+  metadata.gz: 831ee2ea0ab588831a94adb96ed8970bdb05da393e30128c95d1f6daa2355331894edf22b0397a96630e6bada528625bd5fbcf3f86aa76fa76f0fd4af265f6ae
+  data.tar.gz: f7041c8ea3abb6e2ce3570f6d09e0812055354af6a8e0ece2ce7b089be381d0c7de6fe9618bf9f1ef43edb011fc9e713039c87339eb73034d29d17f54a88d250

data/README.md

@@ -2,6 +2,55 @@
 
 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.
 
+## Quick Start
+
+Get up and running in under 2 minutes:
+
+**1. Add the gem and install**
+
+```ruby
+# Gemfile
+gem 'dontbugme'
+```
+
+```bash
+bundle install
+```
+
+**2. Run the installer** (creates config and mounts the Web UI)
+
+```bash
+rails g dontbugme:install
+```
+
+This adds `config/initializers/dontbugme.rb` and mounts the engine at `/inspector` in your routes.
+
+**3. Start your app and generate traffic**
+
+```bash
+rails s          # Start the server
+# In another terminal, if you use Sidekiq:
+bundle exec sidekiq
+```
+
+Make an HTTP request (visit a page, hit an API) or run a Sidekiq job. Dontbugme records automatically in development.
+
+**4. View traces**
+
+**Option A — Web UI (easiest):** Open [http://localhost:3000/inspector](http://localhost:3000/inspector) in your browser. Browse, search, and compare traces.
+
+**Option B — CLI:** From your Rails app root (so it finds the SQLite DB):
+
+```bash
+bundle exec dontbugme list                    # List recent traces
+bundle exec dontbugme show <trace_id>         # Show a trace
+bundle exec dontbugme search --status=error   # Find failed traces
+```
+
+That's it. No database migrations needed — SQLite is used by default in development (`tmp/inspector/inspector.db`).
+
+---
+
 ## Installation
 
 Add to your Gemfile:
@@ -14,6 +63,7 @@ Then run:
 
 ```bash
 bundle install
+rails g dontbugme:install
 ```
 
 ## Usage
@@ -113,29 +163,20 @@ 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)
+### Web UI
 
-A lightweight web interface to browse traces. **Disabled by default in production.** Enable in development:
+A lightweight web interface to browse traces. The installer mounts it at `/inspector`. It's **enabled by default in development** and **disabled in production**.
 
-```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`:
+Visit `/inspector` to browse traces, search, and compare. Tweak in `config/initializers/dontbugme.rb`:
 
 ```ruby
-mount Dontbugme::Engine, at: '/inspector' if Dontbugme.config.enable_web_ui
+config.enable_web_ui = true
+config.web_ui_mount_path = '/inspector'
 ```
 
-Then visit `/inspector` to browse traces, search, and compare.
-
 ### Configuration
 
-Create `config/initializers/dontbugme.rb`:
+Edit `config/initializers/dontbugme.rb` (created by the installer):
 
 ```ruby
 Dontbugme.configure do |config|
@@ -153,15 +194,85 @@ end
 - **PostgreSQL**: Uses your Rails DB. Set `config.store = :postgresql`
 - **Memory**: For tests. Traces lost on process exit.
 
-## Cleanup
+## Production
 
-Traces are ephemeral. Run cleanup to enforce retention:
+In production, Dontbugme uses safer defaults: PostgreSQL storage, async writes, selective recording, and the Web UI disabled. No extra setup is required if you use PostgreSQL — the gem creates the `dontbugme_traces` table automatically.
+
+### Default production behavior
+
+- **Store**: PostgreSQL (uses your Rails DB connection)
+- **Web UI**: Disabled — enable only if you add authentication
+- **Recording**: Selective — always records failures (`record_on_error`), samples successful traces
+- **Async writes**: Enabled to avoid blocking requests/jobs
+
+### Recommended configuration
 
 ```ruby
+# config/initializers/dontbugme.rb
+Dontbugme.configure do |config|
+  config.store = :postgresql
+  config.async_store = true
+
+  # Sample 5% of successful traces to limit storage
+  config.recording_mode = :selective
+  config.sample_rate = 0.05
+  config.record_on_error = true   # Always capture failures
+
+  # Optional: record only specific jobs
+  # config.record_jobs = %w[SendInvoiceJob ProcessPaymentJob]
+  # config.record_requests = :all  # or a proc for custom logic
+end
+```
+
+### Enabling the Web UI in production
+
+If you need the Web UI in production (e.g. for on-call debugging), **protect it with authentication**:
+
+```ruby
+# config/initializers/dontbugme.rb
+Dontbugme.configure do |config|
+  config.enable_web_ui = true
+  config.web_ui_mount_path = '/inspector'
+end
+```
+
+Then add authentication in your routes (e.g. with Devise, `authenticate` before the mount, or HTTP basic auth via a constraint).
+
+### Cleanup and retention
+
+Production defaults to 24-hour retention. Schedule cleanup to enforce it:
+
+```ruby
+# config/schedule.rb (whenever) or a Sidekiq cron job
 Dontbugme::CleanupJob.perform
 ```
 
-Schedule via cron or Sidekiq to run periodically.
+Example with Sidekiq:
+
+```ruby
+# app/jobs/dontbugme_cleanup_job.rb
+class DontbugmeCleanupJob < ApplicationJob
+  queue_as :low
+
+  def perform
+    Dontbugme::CleanupJob.perform
+  end
+end
+# Schedule daily via sidekiq-cron, whenever, or similar
+```
+
+### CLI in production
+
+Run the CLI from your production app directory (or a deploy host with DB access). It uses your Rails DB config:
+
+```bash
+RAILS_ENV=production bundle exec dontbugme list
+RAILS_ENV=production bundle exec dontbugme search --status=error --limit=50
+```
+
+## Cleanup
+
+Traces are ephemeral. Run `Dontbugme::CleanupJob.perform` to enforce retention. See [Production](#production) for scheduling via Sidekiq or cron.
 
 ## Requirements
 

data/lib/dontbugme/railtie.rb

@@ -8,12 +8,14 @@ module Dontbugme
     config.dontbugme = ActiveSupport::OrderedOptions.new
 
     initializer 'dontbugme.configure' do |app|
-      # Configuration defaults are applied in Configuration#initialize
-      # Merge any app-level config (e.g. config.dontbugme.store = :sqlite)
       config = Dontbugme.config
       app.config.dontbugme.each { |k, v| config.send("#{k}=", v) }
     end
 
+    initializer 'dontbugme.middleware' do |app|
+      app.middleware.insert 0, Dontbugme::Middleware::Rack
+    end
+
     initializer 'dontbugme.subscribers' do
       Dontbugme::Subscribers::ActiveRecord.subscribe
       Dontbugme::Subscribers::NetHttp.subscribe
@@ -24,24 +26,18 @@ module Dontbugme
     end
 
     config.after_initialize do
-      # Sidekiq middleware
       if defined?(Sidekiq)
-        Sidekiq.configure_server do |config|
-          config.server_middleware do |chain|
+        Sidekiq.configure_server do |cfg|
+          cfg.server_middleware do |chain|
             chain.add Dontbugme::Middleware::Sidekiq
           end
         end
-        Sidekiq.configure_client do |config|
-          config.client_middleware do |chain|
+        Sidekiq.configure_client do |cfg|
+          cfg.client_middleware do |chain|
             chain.add Dontbugme::Middleware::SidekiqClient
           end
         end
       end
-
-      # Rack middleware
-      if defined?(Rails::Application)
-        Rails.application.config.middleware.insert 0, Dontbugme::Middleware::Rack
-      end
     end
   end
 end

data/lib/dontbugme/recorder.rb

@@ -3,7 +3,7 @@
 module Dontbugme
   class Recorder
     class << self
-      def record(kind:, identifier:, metadata: {}, &block)
+      def record(kind:, identifier:, metadata: {}, return_trace: false, &block)
         return yield unless Dontbugme.config.recording?
         return yield unless should_sample?
 
@@ -14,10 +14,10 @@ module Dontbugme
         trace = Trace.new(kind: kind, identifier: identifier, metadata: metadata)
         Context.current = trace
 
-        yield
+        result = yield
         trace.finish!
         persist(trace)
-        trace
+        return_trace ? trace : result
       rescue StandardError => e
         trace&.finish!(error: e)
         persist(trace) if trace && Dontbugme.config.record_on_error

data/lib/dontbugme/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dontbugme
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/dontbugme.rb

@@ -21,7 +21,7 @@ module Dontbugme
     end
 
     def trace(identifier, metadata: {}, &block)
-      Recorder.record(kind: :custom, identifier: identifier, metadata: metadata, &block)
+      Recorder.record(kind: :custom, identifier: identifier, metadata: metadata, return_trace: true, &block)
     end
 
     def span(name, payload: {}, &block)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dontbugme
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Inspector Contributors
@@ -52,6 +52,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement