Skip to content
baum

Error reporting

baum can send the appliance’s unexpected errors to a Sentry project. Reporting is off unless you enable it, and nothing is sent while it is off.

You choose the project. Use your own Sentry project, or ask Arvina for a project DSN if you want Arvina to see errors for support. Either way, you supply the project’s DSN, and events go only to that project.

Enable reporting

Section titled “Enable reporting”

Copy the DSN from the Sentry project’s Client Keys (DSN) settings. It looks like https://PUBLIC_KEY@o123.ingest.sentry.io/456. Store it, then enable reporting:

Terminal window
sudo baumctl secrets set sentry-dsn
sudo baumctl apply --error-reporting=true

To enable reporting on a new installation, add these flags to your full baumctl install command, with the DSN in a file:

Terminal window
--error-reporting --secret-from-file sentry-dsn=/path/to/sentry-dsn

Install does not prompt for reporting, and leaves it off without --error-reporting.

The DSN must be an http or https URL with the project’s public key as its user name, a host, and a numeric project ID at the end of its path. A path prefix before the ID and a secret key after the public key are accepted. Any other value is refused, and enabling without a valid DSN refuses without changing the installation.

Events carry the environment production unless you name another, for example to separate a staging appliance:

Terminal window
sudo baumctl apply --error-reporting-environment=staging

Pass an empty value, --error-reporting-environment=, to return to production. The same flag works with baumctl install.

The API, the workers and the repository service need outbound access to the DSN’s host, over HTTPS or HTTP as the DSN’s scheme says. An unreachable Sentry never delays or fails the appliance: events that cannot be delivered are dropped.

Change or disable reporting

Section titled “Change or disable reporting”

To use a different project, store its DSN and apply:

Terminal window
sudo baumctl secrets set sentry-dsn
sudo baumctl apply

secrets set alone changes nothing that is running. The next apply notices the new DSN, or a changed environment or enabled state, and restarts the API, the workers, the repository service and the UI to pick it up.

To stop reporting:

Terminal window
sudo baumctl apply --error-reporting=false

The services then receive no DSN or reporting settings. The DSN stays in the secret store; remove it afterwards with sudo baumctl secrets remove sentry-dsn if you no longer need it. Removing it is refused while reporting is enabled.

sudo baumctl status and sudo baumctl doctor show whether reporting is enabled and which environment it uses. Neither prints the DSN. The DSN is kept out of backups and included in encrypted recovery exports, like the other secrets.

What is sent

Section titled “What is sent”

When reporting is enabled, each of these produces an event:

  • Server errors. An API or repository service request that ends in a server error. 502 and 503 responses, which signal that something upstream is unavailable, and client errors (4xx) are not reported.
  • Panics. A panic in the API, the repository service or a worker. A request that panics receives a 500, and the process keeps running. A worker that panics exits as it would without reporting; it is restarted, and its interrupted job is retried.
  • Error records. An error-level structured log record from the API, a worker or the repository service. Output written straight to a log stream produces no event. A failure caused only by the repository service being unreachable (a refused or dropped connection, as during a restart or an update) is not reported where it happens.
  • Repository service outages. The repository service failing its readiness check for five minutes in a row. One event is sent per outage, and the log records when the service is reachable again.
  • Fatal exits. The API, a worker or the repository service exiting with a fatal error. One-off operator commands do not report.
  • Page rendering. An error while the UI renders a page on the server. An error caused by an API 502 or 503 response is not reported.
  • Browser errors. An uncaught error in the browser, or one shown on the UI’s error screen. Not found and other client errors, errors caused by an API 502 or 503 response, and the redirect to the gate are not reported. An error from rendering a page on the server is reported once, by the server, not again by the browser.

The landing page and the gate’s password page report nothing.

Each event carries:

  • the error’s type, message and stack trace
  • the release version, the environment, and the host of the appliance’s public origin
  • which component reported it (api, repository-service, worker or ui), and for workers, the worker role
  • for HTTP errors, the method, route template, status and requested URL without its query string; for browser errors, the page URL without its query string
  • breadcrumbs, with only their category, level, message and timestamp
  • a short list of identifiers such as job, repository and pull request IDs

Everything else is dropped, including request and response bodies, cookies and headers, query strings, browser, OS and device details, user names, email addresses and client IP addresses. Performance traces, session replays, release-health sessions and usage analytics are never sent.

Messages are run through a secret scrubber before they leave the appliance. The scrubber masks detected secrets but cannot guarantee that all sensitive content is removed. Messages can still contain repository or branch names, file paths, or text from upstream API responses. If you cannot share these with the Sentry project’s owner, leave reporting off.

Browser stack traces are minified in any Sentry project other than Arvina’s: release builds upload the UI source maps only to Arvina’s project, and the appliance ships none. Server-side stack traces carry function names, file paths and line numbers.

Browser errors and the gate

Section titled “Browser errors and the gate”

Browsers never receive the DSN. They send their errors to the appliance at /api/error-reports, which scrubs each event and forwards it to your project. That route answers only while reporting is enabled.

With the gate enabled, only callers who pass the gate can submit events. With the gate disabled, anyone who can reach the site can submit events into your Sentry project, up to 60 requests a minute from each address. There is no appliance-wide cap, so callers with many addresses can use up the project’s quota, and the events they submit can describe errors that never happened. Enable the gate, or set rate limits and spike protection in Sentry, if that matters for your installation.