Debug logs
An optional, off-by-default diagnostic log that records what Arris did, never your data. Turn it on to help reproduce an issue, then reveal the file from the Help menu.
Overview
Debug logs are a troubleshooting aid. When something misbehaves, turning on debug mode records a small, curated stream of diagnostic events to a local file you can share or inspect. It is designed so the log is safe to send to support: it captures what happened, not the contents of your work.
Debug mode is off by default. While it is off, nothing is collected and no log file is created at all. While it is on, only the curated events listed below are written. You can toggle it at any time without restarting Arris.
Turning it on
Open Settings, go to the General pane, and toggle Debug mode. Turning it off stops collection immediately. Flipping the toggle takes effect right away, so you can enable it, reproduce the problem, then disable it again.
Opening the logs
Choose Help then Show Debug Logs in Finder from the menu bar.
This opens the debug_logs folder inside the Arris application data directory, where
the log file lives. The menu item creates the folder if it does not exist yet, so it always
opens to the right place.
What is recorded
Each event is a single line of metadata describing an operation Arris performed. Events are emitted on a dedicated channel so that logging from the underlying database driver libraries (which can include raw SQL and parameters) is filtered out and never reaches the file.
Every event carries the connection name you assigned (the conn field) and the
source kind, so you can tell apart two connections of the same kind when debugging.
| Event | Fields recorded |
|---|---|
query.started | Connection name and source kind (for example Postgres). |
query.finished | Connection name, source kind, duration in milliseconds, number of rows returned. |
query.failed | Connection name, source kind, a coarse error code, and a credential-scrubbed error message. |
connection.opened | Connection name and source kind. |
connection.failed | Connection name, source kind, a coarse error code, and a credential-scrubbed error message. |
schema.load.started | Connection name, source kind, and scope (the whole connection, or the schema or dataset being expanded). |
schema.load.finished | Connection name, source kind, scope, duration in milliseconds, and the number of schema nodes returned. |
schema.load.failed | Connection name, source kind, scope, a coarse error code, and a credential-scrubbed error message. |
The schema.load.* events cover browsing the schema tree: listing schemas, datasets,
tables, and their columns. The scope is the schema or dataset identifier being expanded, which
is structural metadata and is what makes it possible to see exactly which load failed when, for
example, a connection lists some datasets but not others.
The error message on a failure is the database driver's own description (for example
relation "foo" does not exist or Connection refused (os error 61)),
which is what makes a failure useful to debug. Before it is written, the message is passed
through a redactor that strips any embedded credentials: userinfo in a connection URI such as
postgres://user:secret@host becomes postgres://<redacted>@host,
and password, token, api_key, and similar assignments are
replaced with <redacted>.
What is never recorded
The log is strictly limited to the metadata above. The following are never written to disk, by design:
- Credentials and secrets: passwords, tokens, API keys, and connection strings.
- Query text: the SQL or statements you run are not logged.
- Query parameters: bound values and literals are not logged.
- Query results: no row data, cell values, or result sets. Only counts and timings.
This guarantee does not depend on scrubbing text after the fact. The file is filtered to a single dedicated event channel, so the verbose output of the database driver libraries, which is where raw SQL and result data would otherwise appear, is dropped before it can be written. The redactor on error messages is a second layer on top of that.
Storage and rotation
Events are appended to debug.log in the debug_logs folder. The file is
size capped: once it reaches 10 MB it rotates to debug.log.1 and a fresh
debug.log is started, so a single previous generation is kept and the logs never
grow without bound. Deleting the files is safe; they are recreated the next time an event is
recorded with debug mode on.