railwatch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c0518c86cb66b33fcb2f673b39aa4f58036369f5cae2412b93d5df3b0cac00c
+  data.tar.gz: def95a2ab24ed33f2b1264c59b0b749edf5dac98901816990775f8b53ad4ffbc
+SHA512:
+  metadata.gz: e3113af0a26ac031fab975b465b6f701a302de6df1e23c896cb883fe77c75fd66748ddcb2b4e6b865fc3adf3dc5c26576eb327220cdc5c32284d0a7a44e42535
+  data.tar.gz: 15e04ae53599352b214a39fab1bc004cdbd264f88596385c1d84393ba0d3357ecd9be43b61f980d5e554e89cafc3f7909a23aa1740427936865b7b6109ae2597

data/AGENTS.md

@@ -0,0 +1,122 @@
+# Railwatch, for coding agents
+
+About *using* the `railwatch` gem from a Rails application; copy
+this into that application's repository. Index of everything else:
+[`llms.txt`](llms.txt).
+
+Railwatch instruments a Rails app end to end and ships linked telemetry to
+Railwatch Cloud. Every request, job attempt, scheduled task run, and command is
+an **execution**; every query, cache read, log line, outgoing HTTP call, view
+render, exception, and span is a child of one, linked by
+`execution_id`/`trace_id`. It never writes to the app's database.
+
+## Install
+
+```sh
+bundle add railwatch
+bin/rails generate railwatch:install --prompt-token --kamal-secrets
+```
+
+The generator writes `config/initializers/railwatch.rb`, mounts `Railwatch::Engine`
+at `/railwatch`, adds the Kamal `post-deploy` hook and the Inertia browser client
+where the app has them, requires `railwatch/rspec` (or `railwatch/minitest`) in the
+test helper, and then runs `railwatch:doctor`. A prompted/stdin/environment token
+goes into `.env` only when Git confirms that file is ignored; token values are
+never printed. Configuration lives only in that
+initializer; every option also has a `RAILWATCH_*` environment variable.
+
+## Rake tasks
+
+| Task | Does |
+|---|---|
+| `bin/rails railwatch:doctor` | ✓/✗ per check: token, ingest URL, reachability, middleware, engine mount, deploy marker, sample rates, ignored types, Kamal hook, browser client and whether an entrypoint calls it, profiler backend, test matchers. Exits non-zero if the token is missing or the host is unreachable. **Run this first when telemetry is missing.** |
+| `bin/rails railwatch:token` | Where to create an ingest token for this app's platform. |
+| `bin/rails railwatch:mcp` | Paste-ready MCP client configuration for this app's platform. |
+| `bin/rails railwatch:deploy[ref,name,url]` | Records a deploy marker. Use as a release step when not deploying with Kamal. |
+| `bin/rails 'railwatch:sourcemaps[public,true]'` | Uploads Vite source maps for the configured deploy, then deletes acknowledged files. Run after building and before publishing assets. Omit `true` to retain files. See [Source maps](docs/source-maps.md). |
+
+## Facade
+
+```ruby
+Railwatch.report(error, handled: true, severity: :warning,
+               context: {order_id: order.id}, fingerprint: ["billing", "stripe"],
+               attachments: {"payload.json" => body})
+Railwatch.attach("payload.json", data, exception: error)
+
+Railwatch.context(tenant: org.slug, plan: org.plan)  # onto the parent record and every exception
+Railwatch.user { |user| {id: user.id, name: user.name, email: user.email} }
+Railwatch.fingerprint { |error, default| error.is_a?(Timeout::Error) ? ["timeout"] : default }
+
+Railwatch.span("pdf.render", template: "invoice", pages: 12) { renderer.call }  # returns the block's value
+Railwatch.instrument_outgoing(:get, url) { client.get(url) }                    # clients with no built-in patch
+Faraday.new(url) { |f| f.use Railwatch::Faraday }                               # Net::HTTP needs nothing
+
+Railwatch.ignore { ExpensiveSync.run }   # also Railwatch.pause / Railwatch.resume
+Railwatch.sample(0.01)                   # re-decide this execution; Railwatch.dont_sample to drop it
+Railwatch.keep!                          # keep this execution whatever the head decision was
+Railwatch.flush                          # ship what's buffered now
+
+Railwatch.redact_queries { |q| q[:sql] = q[:sql].gsub(/'[^']*'/, "'?'") }
+Railwatch.reject_outgoing_requests { |r| r[:host] == "127.0.0.1" }
+Railwatch.reject_cache_keys %w[session: rack::attack*]
+Railwatch.before_ingest { |batch| batch.reject { |r| r[:t] == "log" } }
+Railwatch.on_unrecoverable { |error| Rails.error.report(error, handled: true) }
+```
+
+`redact_*`: requests, queries, exceptions, cache_events, commands, mail,
+outgoing_requests, logs. `reject_*`: queries, cache_events, mail,
+notifications, broadcasts, outgoing_requests, enqueued_jobs, logs.
+
+Per action, in a controller class body: `railwatch_sample 0.01, only: :index`,
+`railwatch_never_sample only: :ping`.
+
+## Specs
+
+`require "railwatch/rspec"` in `spec/rails_helper.rb` (or `"railwatch/minitest"` in
+`test/test_helper.rb`). Railwatch must be enabled in the test env — set any
+non-blank `RAILWATCH_TOKEN`; records go to an in-memory transport, never over the
+wire. All matchers are block matchers.
+
+```ruby
+expect { get "/widgets" }.to have_railwatch_queries(at_most: 6)   # or exactly:/at_least:
+expect { get "/widgets" }.not_to have_railwatch_n_plus_one
+expect { Checkout.new(cart).total }.to record_railwatch_span("checkout.total")
+expect { importer.run }.to record_railwatch_exception(ArgumentError)
+expect { importer.run }.not_to record_railwatch_exceptions
+expect { SyncCustomers.run }.to have_railwatch_outgoing_requests(at_most: 1)
+
+records = railwatch_capture { get "/widgets" }   # everything the block produced
+```
+
+Minitest: `assert_railwatch_queries(at_most: 5) { }`,
+`refute_railwatch_n_plus_one { }`, `assert_railwatch_span("name") { }`.
+
+Use these to hold a hot path to a query budget in CI; failure messages list the
+offending SQL. Seed enough rows that an N+1 actually crosses
+`config.n_plus_one_threshold` (default 5), or the gate passes on code that would
+melt in production.
+
+## MCP
+
+The platform is an MCP server at `<ingest host>/mcp`. Generate a personal
+token at Settings → Profile → "API & MCP token", then:
+
+```sh
+claude mcp add railwatch --transport http https://railwatch.rebulk.com/mcp \
+  --header "Authorization: Bearer lnt_your_token_here"
+```
+
+`bin/rails railwatch:mcp` prints this and the Claude Desktop, Cursor, VS Code, and
+Zed equivalents for whichever platform the app points at. Call
+`list_applications` first; then `list_issues`, `get_issue`, `get_route`,
+`search_requests`, `get_execution`, `explain_query`, `get_profile`,
+`search_logs`, `release_health`, `recent_deploys`, `list_alerts`, and the
+`triage_issue` / `slow_route` / `daily_summary` prompts. All durations are
+milliseconds; these docs are served at `railwatch://docs/<name>`.
+
+## Gotchas
+
+- Sampling is decided **once per execution**; a sampled-out request ships nothing but its unhandled exception.
+- If the app uses WebMock, re-prepend the patch after WebMock loads or outgoing
+  requests are invisible in specs: `Net::HTTP.prepend(Railwatch::Patches::NetHttp)`.
+- Profiling needs `vernier` or `stackprof` in the Gemfile; without one, `profile_sample` does nothing.

data/CHANGELOG.md

@@ -0,0 +1,462 @@
+# Changelog
+
+## 0.1.0 (2026-09-14)
+
+First public release.
+
+- Renamed the gem from Lantern to Railwatch: constants, file paths,
+  `X-Railwatch-*` headers, `RAILWATCH_*` environment variables, rake tasks,
+  the generator, the `/railwatch` mount, and the `railwatch` distribution name.
+  There is no compatibility layer.
+- Prepared the gem for its public RubyGems distribution. Added strict package
+  verification, Trusted Publishing release automation, public
+  security/contribution guidance, TLS verification assertions, an
+  HTTPS-by-default ingest policy, and browser beacon payload hardening.
+
+- Deploy detection follows a git worktree's `.git` file to its gitdir and
+  resolves the branch through the repository's refs, so a development app
+  checked out as a worktree gets a deploy value like a plain clone.
+
+- Reporter backpressure now smooths sustained bursts before the bounded queue
+  starts losing whole executions. On each existing reporter tick, a buffer at
+  80% of either its record or byte ceiling, or an active ingest retry ladder,
+  doubles every execution kind's effective sample divisor up to 8; clear ticks
+  halve it back to 1. It is enabled by default and configurable with
+  `backpressure` / `RAILWATCH_BACKPRESSURE` and `backpressure_high_water` /
+  `RAILWATCH_BACKPRESSURE_HIGH_WATER`. The current divisor rides on deliveries
+  as `X-Railwatch-Backpressure-Factor`, and resets after fork.
+
+- Active Job retries can optionally capture the exception that caused the
+  retry as handled, warning-level telemetry with its attempt and wait in
+  context (`capture_job_retry_errors`,
+  `RAILWATCH_CAPTURE_JOB_RETRY_ERRORS`). It is off by default because retries
+  are usually expected and enabling it can flood the issues list. The
+  existing retry log is unchanged.
+
+- Deploy identifiers are auto-detected without spawning Git: explicit Railwatch
+  and Kamal values first, then common Heroku, Render, Fly, Vercel, GitLab,
+  GitHub, and build environment variables, a Capistrano `REVISION`, and the
+  checkout's loose or packed Git ref. Full SHAs are consistently shortened to
+  12 characters. `RAILWATCH_DETECT_DEPLOY=false` opts out of inferred values,
+  and `railwatch:doctor` reports the selected source.
+
+- `health` records carry the recurring task schedule Solid Queue is
+  running (`detail.recurring_tasks`, key => schedule), so the platform can
+  tell a task that was removed from `config/recurring.yml` apart from one
+  that stopped running. Railwatch Cloud used to flag a removed task as
+  missed every ten minutes for thirty days after its last run. Left out,
+  not sent empty, when there are no tasks or the table could not be read.
+
+- The browser client reports a dropped Inertia request (`networkError` on
+  Inertia 3, `exception` on 2) only while the user is waiting on a visit,
+  meaning one that shows Inertia's progress bar. A visit the page started by
+  itself — a poll, a refresh when the tab comes back, `router.reload`, a
+  prefetch on hover — runs without it, and when one drops its connection
+  nothing the user did has failed: the page keeps what it has and the next
+  tick refreshes it. A laptop waking on a new network used to open an issue
+  that way, and regress it every morning. The visit still lands in timing
+  data with `status: "cancelled"`. A click or a form submit is reported as
+  before, including a click Inertia serves from a prefetch already in
+  flight (which never gets a `start` of its own), and so is the load of a
+  page's deferred props, which the user watches as a skeleton; an app that
+  wants a particular background refresh reported passes `showProgress:
+  true`. Inertia re-rejects a failed request's error after firing the
+  event, and the client now drops that unhandled-rejection copy by identity
+  rather than relying on the reported record to dedupe it.
+
+- Boot with the gem enabled is now within noise of boot without it; it was
+  about 300 ms and 10 MB slower.
+  The `process` record read its adapter names through `ActiveRecord::Base`
+  and `ActiveJob::Base`, which autoloaded both frameworks before anything
+  else asked for them; it now reads the app's configuration. The Rake and
+  `bin/rails runner` patches are installed from the engine's `rake_tasks`
+  and `runner` hooks instead of every boot, which stops a web or worker
+  process requiring rake and railties' runner command.
+- The `process` record is written from an `after_initialize` hook that
+  the engine registers from inside an initializer, so it runs after every
+  `after_initialize` block the app itself registers; `boot_seconds` covers
+  the app's own initializers and those blocks, and an app that reconfigures
+  Railwatch late is respected.
+- Fork handling is one `ActiveSupport::ForkTracker` callback -- Rails' own
+  `Process._fork` hook -- instead of three separate prepends on `Process`.
+  `Railwatch::Reporter::ForkHook`, `Railwatch::Health::ForkHook`, and
+  `Railwatch::Sessions::ForkHook` are gone; `Railwatch.restart_after_fork!`
+  resets everything in order.
+- The gemspec declares `base64` (a bundled gem since Ruby 3.4, previously
+  reached only through Active Support's own dependency) and bounds the
+  Rails dependency to `>= 8.1, < 9`.
+
+- An unhandled exception's urgent flush is coalesced over a quarter-second
+  window (`Reporter::URGENT_FLUSH_DELAY`) instead of waking the reporter
+  per record. During an exception storm every request used to trigger its
+  own POST carrying the handful of records written since the last one: a
+  ten-second burst that produced 4,000 records went out as 400 POSTs of
+  ten, at about double the gzip bytes per record of a full batch. A lone
+  exception still ships within the window; a buffer that crosses
+  `flush_threshold` flushes at once as before.
+
+- `POST /railwatch/beacon` is rate limited per client IP: 120 requests a
+  minute by default (`beacon_rate_limit`, `RAILWATCH_BEACON_RATE_LIMIT`; `0`
+  disables), answered with 429 and `Retry-After` past that. The beacon takes
+  no credential and keeps every browser error it is sent, so until now a
+  script could spend an app's event quota and open junk browser issues from
+  a shell. The counter lives in the app's cache store; a store that cannot
+  count fails open.
+- **Behaviour change for every app: `query` records now carry normalized SQL,
+  not the raw statement.** String, numeric, hex, Postgres dollar-quoted and
+  adapter-specific literals, plus SQL comments, are replaced with `?` while
+  the statement shape and placeholders remain. SQL literals routinely contain
+  email addresses, tokens, and other customer data, and until now every one of
+  them was shipped. Set `capture_sql_values` (`RAILWATCH_CAPTURE_SQL_VALUES`) to
+  restore the old behaviour. Active Record's separate structured binds are
+  never sent either way, and `capture_query_explain` is unaffected -- the
+  EXPLAIN still runs on the raw statement, only what is stored in `sql`
+  changed. Note that a plan can echo literal predicates, so
+  `capture_query_explain` remains a privacy decision of its own.
+- The SQL normalizer is a byte-oriented lexical scanner rather than a set of
+  regexes: adapter-aware quoting (MySQL backticks and double-quoted strings,
+  SQLite `[ident]` and its double-quoted-string fallback, Postgres
+  dollar-quoting and `E''`), nested block comments, and bounded input. It
+  scans each dialect's *default* backslash-escaping rule. Session modes that
+  change that rule (`NO_BACKSLASH_ESCAPES`, `standard_conforming_strings =
+  off`) are not carried in the notification; the previous approach of
+  abandoning the rest of the statement whenever a backslash-quote appeared
+  was worse, because on MySQL -- where backslash escaping is the quoting
+  Active Record emits -- it truncated every statement containing an
+  apostrophe and collapsed distinct queries into one group.
+
+- Telemetry memory is now bounded by bytes as well as by record count. A
+  record count alone does not bound memory: 10,000 records is a few megabytes
+  of ordinary telemetry, or a gigabyte of captured attachments and
+  multi-megabyte SQL strings. Three new ceilings, all configurable:
+  `buffer_bytes` (16 MiB, reporter queue), `execution_buffer_bytes` (8 MiB,
+  one execution's buffered tree), and `batch_bytes` (8 MiB uncompressed
+  NDJSON per ingest request). Each record is weighed once, when it is
+  buffered, and the weight travels with it, so nothing is measured twice.
+  Byte loss is counted and reported alongside record loss
+  (`X-Railwatch-Dropped-Bytes`).
+- A queue holding more than one batch is delivered as several batches; the
+  tail is kept for the next flush rather than dropped. A record that still
+  does not fit one delivery is dropped and counted rather than raising -- a
+  batch that is too large is exactly as large on the next attempt, so
+  retrying it would burn all eight attempts and drop it anyway.
+- `Railwatch.attach` reads a file or IO with a bounded `cap + 1` read. A 2GB
+  log file used to be read whole and then sliced to 1 MiB.
+
+- User references survive a tenant that binds after the user is resolved.
+  An app that resolves its user in one `before_action` and its tenant in the
+  next used to emit a bare `"1"` for every tenant's user 1 -- two tenants
+  collapsed onto one person on the platform. The execution now keeps the raw
+  id and requalifies it (plus the records already buffered, and the pending
+  `user` entity) the moment the tenant binds, so the final reference is
+  `"acme:1"` and the entity is deduplicated against that final reference
+  rather than the provisional one. Jobs enqueued from such a request carry
+  the raw id and the tenant, and the worker qualifies it on restore.
+- `Railwatch.context(tenant: ...)` now actually sets the tenant on records, as
+  documented. It binds onto the running execution at `Railwatch.context` time;
+  `Context.current_tenant` reads that before falling back to `TenantRecord` /
+  `ActiveRecord::Tenanted`, so nothing on the per-record path pays for it.
+
+- A `user` entity is now cached (one per id per process-hour) only after the
+  execution that carried it was actually handed to the reporter. Previously
+  the first sighting wrote the cache entry unconditionally, so if that
+  sighting happened inside a sampled-out or `Railwatch.pause`d execution -- or
+  an execution whose sampling flipped afterwards -- no `user` record was ever
+  written, and every sampled-in sighting for the next hour was suppressed:
+  the platform had records attributed to a user it had no name or email for.
+  Forked workers also reset the cache, since a child's reporter buffer starts
+  empty and has to emit its own entities.
+
+
+
+- Action Cable channel actions now open a real `channel_action` execution
+  before application code runs, so the queries, logs, broadcasts, transmits,
+  and unhandled exceptions inside an action share one execution and one trace.
+  A channel action has no HTTP request and no Rack middleware around it, so
+  until now those records had no parent at all. Head sampling is its own knob,
+  `sample[:channels]` / `RAILWATCH_CHANNEL_SAMPLE_RATE`; an unhandled channel
+  exception still ships with its parent when the channel rate is zero.
+
+- `Railwatch.context` is now redacted with the same `ActiveSupport::ParameterFilter`
+  that redacts request params. Context is application data and gets copied
+  onto every record built while it is set, so an app that put an API token or
+  a password there was writing it verbatim into telemetry.
+- An oversized context is now rebuilt rather than sliced. The 64KB cap used
+  to `byteslice` the encoded JSON, which cut it mid-string or mid-object and
+  left the platform with an unparseable fragment -- the whole context was
+  lost rather than most of it. Whole values are kept while they fit, an
+  oversized string value ends with `[TRUNCATED]`, anything that still does
+  not fit is dropped, and `"_railwatch_truncated": true` says it happened. The
+  empty-context fast path (which runs on every log record) is unchanged.
+
+- Request teardown no longer parses a non-multipart request body. Emitting
+  the `request` record read `request.params` (for `files`) and
+  `request.format`, and Rack parses the body the first time either is asked
+  for. When a controller ran, that parse had already happened and was
+  memoized; when nothing ran -- a routing 404, a rack-attack block, an
+  upstream rejection -- Railwatch was the only component that ever read the
+  body, at teardown, after the response was decided. Both reads are now
+  guarded: `files` falls back to walking params only for a multipart request
+  (nothing else can carry an upload), and `format` is reported only when it
+  is already resolved or the request is multipart, otherwise `""`.
+
+- Ingest acknowledgements are validated before a batch is considered
+  delivered: a 2xx whose body is not a JSON object, is malformed JSON, omits
+  `accepted`/`rejected`, or reports counts that do not cover the submitted
+  batch now retains the batch (under the same idempotency key) for retry
+  instead of silently dropping it. HTML sign-in pages from an intercepting
+  proxy were the motivating case. Two shapes are explicitly a successful
+  drain rather than a failure: an acknowledgement carrying a `reason`, and an
+  all-zero `{"accepted":0,"rejected":0}` -- that is how the platform answers
+  for a paused or over-quota environment, and retrying it would burn eight
+  attempts and drop the records anyway. Per-record rejections
+  (`rejected > 0`) stay routine: they are logged under `RAILWATCH_DEBUG` and
+  are not reported to `on_unrecoverable`, since the platform's ingest batch
+  is the authoritative accounting for them.
+- Per-request overhead roughly halved, and per-query overhead cut by about
+  two thirds, measured against a baseline with the gem's subscribers
+  genuinely unsubscribed. The log capture reported itself at DEBUG, which
+  made `Rails.logger.debug?` true for the whole app and had every framework
+  `LogSubscriber` format its SQL, render, and cache lines for nobody; it
+  now reports `config.log_level`. A head-sampled-out request no longer
+  builds the request record it was about to discard. The transaction
+  statement counter shares the query subscriber's event instead of taking
+  a second one per query, and the model-hydration counter subscribes
+  without an `Event` object. Cache-event and view-render group hashes,
+  the vendor cache-key check, and the `GC.stat(:time)` probe are computed
+  once instead of per event.
+
+- `bench/overhead.rb` now measures against a real baseline: every
+  subscriber the gem installed is unsubscribed and its log capture detached
+  for the "off" batches, rather than flipping `config.enabled` with
+  everything still wired in, which had hidden most of the cost. It gates
+  three request shapes on SQLite and fails if `Rails.logger.debug?` is on.
+  The scripts that produced the numbers in the docs are committed alongside
+  it and indexed in `bench/README.md`: per-shape cost, the request, query,
+  and exception paths piece by piece, reporter-thread and wire cost,
+  allocation and CPU attribution, and an end-to-end Puma load harness.
+
+- The installer now prefers a hidden prompt, stdin, or `RAILWATCH_TOKEN`, never
+  prints token values, and refuses to put a token in a tracked or non-ignored
+  `.env`. `railwatch:doctor` also fails when it finds a plaintext `lt_...` token
+  in likely secret-bearing files tracked by Git. The legacy `--token=` option
+  remains compatible but warns about shell-history and process-list exposure.
+
+- A forked worker profiles again. `Process._fork` now resets the profiler's
+  process-global state in the child: it used to inherit `@running` holding
+  the handle of a profile the parent was taking, which nothing in the child
+  ever stopped, so every execution in that worker was counted as skipped and
+  never profiled for the life of the process.
+
+- Numeric `RAILWATCH_*` environment variables are parsed with `Integer()`/
+  `Float()` and fall back to the documented default when the value is not a
+  number. `RAILWATCH_BUFFER_SIZE=12px` used to become `0` via `String#to_i`,
+  silently turning off buffering; the same applied to timeouts, intervals
+  and sample rates.
+
+- Inbound `traceparent` parsing follows the W3C trace-context validity
+  rules: version `ff`, an all-zero trace id, and an all-zero parent id are
+  rejected instead of being adopted as a trace, and trailing data after the
+  flags is rejected on version `00`. A future version that appends
+  dash-delimited fields after the flags is now accepted (its extra fields
+  are never interpreted) rather than dropped, so a newer upstream still
+  links to this service.
+
+- The request record's `url` and `redirect_to` URL fields now retain only
+  origin (without authority credentials) and path. Query strings and
+  fragments are always removed from these fields, preventing reset tokens,
+  OAuth codes, signed-URL credentials, and other parameter values from being
+  exported even when request-payload capture is disabled. The Net::HTTP and
+  Faraday patches sanitize an `outgoing_request` URL through the same
+  helper, so authority credentials and fragments are now dropped there too.
+
+- Exception deduplication is now scoped to the current execution and to the
+  handled/unhandled disposition, and only marks an error after sampling and
+  pause checks pass. A sampled-out or paused handled report can no longer
+  suppress a later unhandled raise of the same object, while Rails.error and
+  middleware still collapse duplicate observations in one execution.
+
+- Header masking no longer depends on an app enumerating every vendor
+  header name. A header whose name has a credential-shaped segment
+  (`api-key`/`apikey`, `access-key`/`accesstoken`, `private-key`,
+  `auth`/`authentication`/`authorization`, `bearer`, `credential`, `hmac`,
+  `jwt`, `token`, `secret`, `signature`) is masked as `[FILTERED]` on top of
+  the exact `redact_headers` denylist. Concatenated Rack aliases such as
+  `X-AuthToken`, `X-ApiToken`, `X-AccessToken`, `X-ClientToken`,
+  `X-SessionToken`, `X-RefreshToken`, `X-SecretKey`, `X-HmacSignature`, and
+  `X-CSRFToken` are covered alongside `X-Api-Key`, `Stripe-Signature`, and
+  `X-Hub-Signature-256`. Ordinary diagnostic headers are untouched.
+
+- `buffer_size` defaults to 10,000 (was 5,000), matching
+  `Execution::MAX_RECORDS`. A job whose tree was larger than the queue lost
+  its first records when the tree was written at the end of the execution;
+  on rebulk-system that was every outgoing HTTP request of a 30-second sync.
+
+- Active Job payloads now carry the enqueuing execution's user and tenant
+  (`railwatch_user`/`railwatch_tenant`) next to the trace and parent ids, and
+  the worker restores them before the attempt opens. A `job_attempt` and
+  every child record under it are attributed to the person whose request
+  enqueued the job instead of to a worker process with no signed-in user,
+  and jobs that enqueue jobs pass the same identity along. Identifier
+  strings only — no user or tenant model is serialized or hydrated.
+  Payloads without the keys (enqueued before this change) deserialize to
+  nil and fall back to local resolution as before.
+
+- `c.failure_context = 200` (`RAILWATCH_FAILURE_CONTEXT`) keeps a
+  head-sampled-out execution's last 200 child records in a ring and ships
+  them only if that execution reports an unhandled exception, so an
+  unsampled failure is diagnosable without enabling slow-request tail
+  sampling globally. Off (0) by default, which leaves the sampled-out path
+  building and buffering nothing exactly as before. `exceptions: 0`,
+  ignored and handled exceptions, `Railwatch.pause`/`ignore`, and an
+  interactive `rails runner` never promote a ring; overflow is counted onto
+  the batch's dropped-record count; with `tail_sample_slow_ms` also set,
+  tail sampling's larger buffer wins.
+
+- A retained delivery batch gives up after `Reporter::MAX_RETRY_ATTEMPTS`
+  (8) and is dropped and counted, so a batch that keeps failing cannot pin
+  itself in memory while every newer record is discarded around it.
+
+- `c.beacon_user { |request| ... }`: who is behind a browser beacon, for
+  apps that authenticate in a `before_action` the gem's beacon controller
+  never runs. Before this, every visit, browser session and JavaScript
+  error from such an app shipped with no user.
+- Console breadcrumbs render objects as JSON instead of `[object Object]`.
+
+- `bin/rails runner` from a shell never got its command execution: the
+  runner patch is prepended during `boot_application!`, which the
+  already-running `#perform` calls, so the `#perform` override only ever
+  ran in this gem's own specs. The patch now also wraps
+  `conditional_executor`, which that `#perform` reaches after boot, so a
+  real runner ships its `command` record and an interactive one (`-`,
+  inline code, a script under `/tmp`) withholds its exception as documented.
+
+- Forked Puma and Active Job workers now replace inherited reporter buffers,
+  drop accounting, transport policy state, and synchronization primitives
+  before recording anything. Parent telemetry is delivered only by the
+  parent; each child emits its own process/health records, and a mutex held
+  by another thread at fork can no longer deadlock the child reporter.
+
+- Exceptions whose backtrace was assigned rather than raised
+  (`ActiveRecord::StatementInvalid` via `set_backtrace`, `Faraday::Error`
+  delegating to its wrapped exception) shipped with no frames, no
+  culprit, and a fingerprint of class and message only, because
+  `backtrace_locations` is nil for them. `Backtrace.frames` now parses the
+  String backtrace in that case.
+
+- Request exclusions now bypass instrumentation correctly. `/up` and
+  `/railwatch/beacon` are excluded by default, apps can configure exact paths
+  or regexps through `ignored_request_paths`, and a same-origin authenticated
+  reporter POST to `/ingest` is recognized behind reverse proxies. The last
+  case prevents Railwatch Cloud's self-monitoring from creating an endless
+  flush -> ingest-request -> flush feedback loop without hiding unrelated
+  application routes also named `/ingest`.
+
+- Retryable ingest failures no longer discard a drained batch. Network
+  failures plus HTTP 402, 408, 429, and 5xx responses restore records and
+  their drop accounting to the bounded buffer, then retry on the reporter
+  thread with jittered exponential backoff. Permanent client rejections and
+  shutdown deadlines with unsent records remain observable through
+  `on_unrecoverable`; urgent exception reporting now wakes the background
+  thread instead of waiting through network timeouts on the request thread.
+
+- Browser JavaScript errors. The Inertia browser client now captures
+  uncaught errors, unhandled promise rejections, and Inertia's failed-request
+  events (`exception`/`invalid` on Inertia 2, `networkError`/`httpException`
+  on Inertia 3), batches them onto the existing beacon, and the
+  beacon controller records each as an `exception` with `source: "browser"`
+  — stack parsed into the same `{file, line, function, in_app}` frames a
+  Ruby backtrace produces, and the same default fingerprint, so a browser
+  error groups, regresses and resolves like any other issue. Each error
+  carries the page URL, Inertia component, visit, tab session, user agent,
+  and the last 20 breadcrumbs (console errors, clicks, navigations).
+  `startRailwatch({ ignoreErrors, denyUrls, tenant })`, plus
+  `railwatchRootOptions()` for React 19's `createRoot` and
+  `reportError(error, context)` for a React 18 boundary — outside a
+  development build React never hands a boundary-caught error to
+  `window.onerror`. Replaces `@sentry/react`; see
+  `docs/replacing-sentry.md`.
+
+- Interactive sessions are no longer treated as application failures.
+  `bin/rails console` captures nothing, starts no background thread, and
+  sends no `process`/`health` record (`config.capture_console` /
+  `RAILWATCH_CAPTURE_CONSOLE=1` re-enables everything). A `bin/rails runner`
+  the operator typed (`-`, inline code, or a `.rb` file under
+  `config.interactive_runner_paths`, default `/tmp/` and `/var/tmp/`) ships
+  its `command` record with `interactive: true` and its exit code, but does
+  not report the exception; a deployed script (`rails runner
+  script/nightly.rb`), a rake task, and a job report exactly as before.
+
+- Release health: a new `session` record type, from the browser client (one
+  session per tab, riding along on the visit beacon) and from the request
+  middleware (`Railwatch::Sessions`, one flusher thread per web process).
+  `config.track_sessions`, `config.session_flush_interval`,
+  `config.session_timeout`; `c.ignore = [:sessions]` turns off shipping.
+
+- Added `docs/records.md` (every wire record type, field by field) and
+  `docs/configuration.md` (every `Configuration` attribute, the public
+  facade, sampling, transport, Inertia beacon/SSR, the overhead gate, the
+  Kamal hook, and the rake tasks); README tightened to point at both,
+  plus a new "Replacing Sentry" section.
+- Initial release: requests, jobs, scheduled tasks, commands, queries (with
+  N+1 detection), transactions, exceptions, cache, mail, Action Cable
+  broadcasts, Noticed notifications, outgoing HTTP, Active Storage, view
+  renders, logs and Rails 8.1 structured events, deprecations, users,
+  processes, and Inertia visits. Sampling, ignore/pause, redaction,
+  rejection, before-ingest rate limiting, deploy tracking, Kamal hook.
+- Job attempts report `status` (`released` when `retry_on` re-enqueues instead
+  of failing), `queue_latency` measured at perform-start rather than after the
+  job runs, `connection`, and `concurrency_key`; a pruned job attempt gets a
+  fresh `execution_id`/`trace_id` instead of reusing a stale one.
+- `process` records measure `boot_seconds` from `Railwatch::BOOTED_AT`, a clock
+  reading taken as early in process boot as Railwatch can observe, instead of an
+  unset global.
+- `bin/rails runner` invocations are instrumented as a `command` execution.
+- Inertia SSR renders are timed automatically (`inertia.ssr_ms`) wherever
+  `inertia_rails` SSR is enabled, including full-page (non-XHR) visits.
+- Exceptions report `code` (errno, for a `SystemCallError`) and `sql_state`.
+- Transactions report `statement_count` (writes made inside the transaction)
+  and a `group` hash for grouping in the UI.
+- Default vendor rake tasks (`db:migrate`, `assets:precompile`, ...) and
+  default vendor cache-key prefixes (`rack::attack`, `flipper`, ...) are
+  excluded by default; opt back in with `capture_default_vendor_commands` /
+  `capture_default_vendor_cache_keys`.
+- `Railwatch.reject_cache_keys` drops your own noisy cache keys the same way as
+  the default vendor list, with trailing-`*` prefix matching and regex support.
+- A request sampled out together with `sample[:exceptions] = 0` now ships
+  nothing for an unhandled exception, instead of always shipping one.
+- Requests report `route_methods`, `route_domain`, and uploaded `files`
+  (name/size/content_type only, never file contents).
+- `Railwatch.on_unrecoverable` registers a callback for Railwatch's own internal
+  errors (a subscriber raising, or delivery failing after its retry).
+- `Railwatch::Faraday` middleware instruments outgoing HTTP made through
+  Faraday (`f.use Railwatch::Faraday`); `Railwatch.instrument_outgoing(method,
+  url) { }` covers any other HTTP client.
+- Fixed `Backtrace.caller_location` excluding legitimate app/spec frames that
+  happened to live under a path containing "/railwatch/" (this gem's own
+  `spec/dummy`, for one); it now only skips Railwatch's own `lib/` and frames
+  inside an installed gem, so query and outgoing-request source locations
+  resolve correctly again.
+- Fixed `railwatch:status` and `railwatch:deploy` rake tasks running twice per
+  invocation: the engine no longer manually `load`s `lib/tasks/railwatch_tasks.rake`
+  on top of Rails' automatic `lib/tasks/*.rake` loading.
+- `Transport::Http` is now HTTP-status-aware: a 5xx response is retried once,
+  a 4xx is not retried, a 401 marks the reporter unauthorized and stops
+  flushing (logged once via `Railwatch.debug` and `Railwatch.on_unrecoverable`),
+  and a 402 (quota) backs off for 60 seconds, dropping and counting records
+  as dropped during the backoff window. Delivery still never raises.
+- Fixed `Patches::RakeTask` shipping a separate command record per
+  prerequisite instead of nesting the whole dependency chain under one
+  command execution; nested calls made from inside an already-excluded
+  vendor task (e.g. `db:_dump`, invoked internally by `db:migrate`) are also
+  left untracked instead of starting their own execution.
+- `job_attempt` records now include `parent_id` (the enqueuing execution's
+  id), previously captured but never emitted in the shipped hash.
+- Fixed `Patches.install_runner_command!` requiring the wrong path for
+  `Rails::Command::RunnerCommand` (`rails/command/runner_command` instead of
+  `rails/commands/runner/runner_command`), which silently no-oped and left
+  `bin/rails runner` uninstrumented.
+- `Configuration#ignore=` now raises `ArgumentError` for a record type
+  outside `RECORD_TYPES` instead of silently accepting it.
+- `scheduled_task` records report `drift` (microseconds between the
+  `RecurringExecution#run_at` and the actual perform start).

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Cole Robertson and Rebulk
+
+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.