railwatch 0.5.1 → 0.6.1

data/lib/railwatch.rb

@@ -343,10 +343,32 @@ module Railwatch
 
     # Called (rescued) whenever the gem itself rescues an internal exception:
     # a subscriber block raising, or delivery failing after its retry.
-    # Falls back to the debug log when no callback is registered.
+    #
+    # With no callback registered, an internal error goes to the debug log:
+    # the gem recovered, and a subscriber that raises once is noise in
+    # someone else's cron output. A DeliveryError is different. It is raised
+    # only when records are already gone -- a batch dropped after the retry
+    # ladder, one the receiver permanently refused, or the ones still unsent
+    # when at_exit's bounded shutdown ran out of time -- and since 0.3.7 that
+    # shutdown is the only delivery a rake task or runner gets. Behind
+    # RAILWATCH_DEBUG that loss was invisible: a cron job whose exception
+    # never reached the platform looked exactly like one that had nothing to
+    # say.
+    #
+    # It is still not printed by default. A monitoring gem writing into
+    # someone else's cron output is the gem changing their application's
+    # behaviour, which is not a trade this one makes to report on itself: it
+    # stays additive and out of the way. Ask for it with warn_on_data_loss and
+    # it becomes one stderr line, or register on_unrecoverable and route it
+    # wherever the app already sends such things. Kernel#warn, not
+    # Rails.logger, for the same reason as #debug: it must never become a log
+    # record about itself.
     def notify_unrecoverable(error)
       if config.on_unrecoverable
         config.on_unrecoverable.call(error)
+      elsif error.is_a?(Reporter::DeliveryError) && config.warn_on_data_loss
+        warn("[railwatch] #{error.message}. Register Railwatch.on_unrecoverable to route this elsewhere, " \
+             "or set warn_on_data_loss = false to silence it.")
       else
         debug { "unrecoverable internal error: #{error.class}: #{error.message}" }
       end

data/lib/tasks/railwatch_tasks.rake

@@ -235,7 +235,7 @@ namespace :railwatch do
       %w[railwatch railwatch_telemetry].each do |name|
         configured = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env, name: name)
         check.call(!configured.nil?, "#{name} database",
-                   configured ? configured.database : "not in config/database.yml (bin/rails generate railwatch:install --local)",
+                   configured ? configured.database : "not in config/database.yml (bin/rails generate railwatch:install)",
                    fatal: true)
       end
       { "railwatch_telemetry" => Railwatch::TelemetryRecord, "railwatch" => Railwatch::ApplicationRecord }.each do |name, base|
@@ -326,12 +326,19 @@ namespace :railwatch do
       # HTTP Basic is on and closed until credentials exist; a deploy that
       # forgot gets a 401, not a public page, and this says so first.
       gate = config.dashboard_gate
-      check.call(gate != :undeclared && !(gate == :basic && !config.http_basic_auth_configured?), "dashboard access",
+      check.call(gate != :undeclared && !(gate == :basic && !config.http_basic_auth_configured? && !config.http_basic_auth_waived?),
+                 "dashboard access",
                  case gate
                  when :basic
-                   config.http_basic_auth_configured? ? "HTTP Basic, user #{config.http_basic_auth_user}" :
+                   if config.http_basic_auth_configured?
+                     "HTTP Basic, user #{config.http_basic_auth_user}"
+                   elsif config.http_basic_auth_waived?
+                     "open in development. Production stays closed until you run " \
+                       "`RAILS_ENV=production bin/rails railwatch:authentication:configure`"
+                   else
                      "closed: HTTP Basic is on with no credentials, so every dashboard request is 401. " \
-                     "Run `bin/rails railwatch:authentication:configure`"
+                       "Run `bin/rails railwatch:authentication:configure`"
+                   end
                  when :controller then "your own: c.base_controller_class = #{config.base_controller_class}"
                  when :resolver then "your own: c.dashboard_user decides, and live updates follow it"
                  when :open then "deliberately open: anyone who can reach the mount can read it (c.dashboard_open)"

data/llms.txt

@@ -3,35 +3,42 @@
 > Railwatch is a Ruby gem that instruments a Rails application end to end —
 > requests, jobs, scheduled tasks, rake/runner commands, database queries and
 > N+1s, exceptions, cache, mail, notifications, broadcasts, outgoing HTTP,
-> Active Storage, view renders, and logs — links every one of them into a
-> single execution tree by `execution_id`/`trace_id`, and ships them to
-> Railwatch Cloud from a background thread. It replaces a separate APM and a
+> Active Storage, view renders, RubyLLM calls, and logs — links every one of
+> them into a single execution tree by `execution_id`/`trace_id`, and writes
+> them from a background thread into two SQLite files the app owns (embedded,
+> the default) or to Railwatch Cloud. It replaces a separate APM and a
 > separate error tracker with one gem and one configuration block, costs
 > under a millisecond of CPU per request, and never writes to the
-> application's own database. Install is `bundle add railwatch` followed by
-> `bin/rails generate railwatch:install`, which writes the initializer, mounts
-> the beacon engine, adds a Kamal post-deploy hook and the Inertia browser
-> client where the app has them, wires the test matchers, and then runs
-> `bin/rails railwatch:doctor` to print a ✓/✗ line for every piece.
+> application's primary database. Install is `bundle add railwatch` followed
+> by `bin/rails generate railwatch:install`, which by default keeps
+> everything in the app (two SQLite databases, a Puma writer process, the
+> dashboard at `/railwatch`, open in development and password-protected
+> elsewhere); with `--cloud` or a token option it sends to Railwatch Cloud
+> instead, and an embedded install can export to the cloud as well. It
+> writes the initializer, mounts the engine, adds a Kamal post-deploy hook
+> and the Inertia browser client where the app has them, and wires the test
+> matchers. `bin/rails railwatch:doctor` prints a ✓/✗ line for every piece.
 
 ## Docs
 
-- [README](README.md): what Railwatch is, the install, sampling, spans, profiling, tail sampling, and the Sentry option mapping table.
-- [Getting started](docs/getting-started.md): five-minute install for a Rails 8 app, where the token comes from, the three optional lines, and deploying under Kamal, Docker/Heroku/Render, or no deploy tool at all.
+- [README](README.md): what Railwatch is, the install, embedded mode, and where each document fits.
+- [Getting started](docs/getting-started.md): the two-command embedded install, the Railwatch Cloud install and where its token comes from, the three optional lines, and deploying under Kamal, Docker/Heroku/Render, or no deploy tool at all.
+- [Embedded mode](docs/embedded.md): the default install — the dashboard inside the app, its two SQLite databases, dashboard authentication, the Puma writer process, maintenance without a job worker, disk reclaim, and optional export to Railwatch Cloud.
 - [Configuration](docs/configuration.md): every configuration option and its `RAILWATCH_*` environment variable, plus the full public facade, redaction, rejection, transport and buffering behaviour, and the rake tasks.
-- [Record types](docs/records.md): every record type the gem ships and every attribute on it, sourced from the code that builds it.
+- [Record types](docs/records.md): every record type the gem ships and every attribute on it, including RubyLLM calls (tokens, cost, finish reason, tool calls, workflows), sourced from the code that builds it.
 - [Testing](docs/testing.md): the RSpec and Minitest matchers (`have_railwatch_queries`, `have_railwatch_n_plus_one`, `record_railwatch_span`, `record_railwatch_exception`, `have_railwatch_outgoing_requests`) and a CI performance-gate recipe.
 - [Production source maps](docs/source-maps.md): hidden Vite maps, private upload before publishing assets, safe opt-in deletion, resolved browser stacks and default issue grouping.
-- [AI assistants and MCP](docs/ai-and-mcp.md): the MCP endpoint, how to get a token, paste-ready client configuration for Claude Code, Claude Desktop, Cursor, VS Code, and Zed, and every tool, prompt, and resource the server exposes.
+- [AI assistants and MCP](docs/ai-and-mcp.md): Railwatch Cloud's MCP endpoint, how to get a token, paste-ready client configuration for Claude Code, Claude Desktop, Cursor, VS Code, and Zed, and every tool, prompt, and resource the server exposes.
 - [Replacing Sentry](docs/replacing-sentry.md): a step-by-step migration — removing the gems, porting each option, rewriting each call site, breadcrumbs, spans, profiling, attachments, `before_send`, fingerprints, and release health.
 - [Coming from Laravel Nightwatch](docs/replacing-nightwatch.md): the record-type mapping, what "execution" means in Railwatch, sampling parity, and the facade method names in Ruby.
 - [Self-hosting](docs/self-hosting.md): pointing the gem at a self-hosted Railwatch Cloud, creating a token there, and checking the connection.
-- [Troubleshooting](docs/troubleshooting.md): every failure mode paired with the `railwatch:doctor` line it shows up as — no records, doubled scheduled tasks, WebMock in specs, Puma fork, tail-sampling memory, missing profiler, missing deploy marker, Kamal hook, log search, empty tenants.
+- [Troubleshooting](docs/troubleshooting.md): every `railwatch:doctor` line, embedded and cloud, and the failure modes behind them — no records, doubled scheduled tasks, WebMock in specs, Puma fork, tail-sampling memory, missing profiler, missing deploy marker, Kamal hook, log search, empty tenants.
+- [Security](docs/security.md): transport, capture defaults, the browser beacon, token handling, and application responsibilities.
 - [FAQ](docs/faq.md): overhead numbers and how they are measured, retention, what is redacted by default versus opt-in, SQLite, and what happens when the platform is unreachable.
 
 ## For coding agents
 
-- [AGENTS.md](AGENTS.md): how to install and use Railwatch from inside a Rails app — the facade methods, the spec matchers, `railwatch:doctor`, and the MCP hookup. Duplicated verbatim as [CLAUDE.md](CLAUDE.md).
+- [AGENTS.md](AGENTS.md): how to install and use Railwatch from inside a Rails app — the facade methods, the spec matchers, `railwatch:doctor`, and the Railwatch Cloud MCP hookup.
 
 ## Optional