Logs and health

Logs

Gansey always logs readable lines to the console. While gansey serve runs with [logs].to_file on, every event is also written as one JSON object per line to <logs dir>/gansey.log.<date>, with a new file each day. Old files are pruned when the server starts and once a day after that: files last changed more than keep_days days ago are deleted, and keep_days = 0 keeps every file. One-off commands such as gansey backup now log to the console only.

[logs]
dir = "./data/logs"
to_file = true
keep_days = 14

Each JSON line carries a timestamp, a level, a target and a fields object holding the message and the event's own fields, so a log shipper can read them without parsing text. If the logs folder cannot be created the server says so and carries on with console logging.

Which events are logged is set by RUST_LOG, which defaults to info,gansey=debug,tower_http=info. Requests are traced at debug level, so RUST_LOG=info,tower_http=debug adds lines for each request.

Variable	What it does
GANSEY_LOG_DIR	moves the log files
GANSEY_LOG_FILE	false keeps logging to the console only
GANSEY_LOG_KEEP_DAYS	days of files to keep
RUST_LOG	which events are logged, and how much detail

Without email set up, messages Gansey would have sent (sign-in links among them) are written to the log instead. Treat log files as sensitive.

The dashboard's Core health area

The dashboard shows how the site is doing: environment and uptime, the database and its migrations, users and active sessions, pages, media, backups (the last one and the next nightly), updates and the licence, indexing, email, log files and the animation runtime. A warning dot marks anything that needs attention, such as missing backup tools or an update waiting.

GET /api/health

A public endpoint for load balancers, container health checks and monitoring services. It answers 200 with a small JSON document while the process is up:

{ "status": "ok", "version": "0.2.1", "database": "ok", "widget_kinds": ["button", "heading", "..."] }

database is ok, unreachable or not configured. The status code does not change when the database is unreachable, so a monitor that needs the database should check that field too.

curl -fsS https://example.test/api/health

GET /api/health/detail

Everything the Core health area shows, as JSON, for monitoring that can sign in. It needs a signed-in session (any role). It reports:

Field	What it holds
version, platform, environment, uptime_seconds	the running binary
database	configured, ok, migrations_applied, migrations_total
users, sessions_active	how many accounts and live sessions
pages	total, published, drafts, scheduled
media	root, items, bytes, writable
backups	count, last, next_nightly, dir, and which tools are found
updates	the last check: channel, latest version, licence state, errors; null until a check has run
email_configured, error_reporting, animation_runtime	true or false
logs	to_file, dir, keep_days, files, bytes
indexing	indexable, noindex_setting, environment_allows
render_cache_pages, widget_kinds	pages in the page cache, widget kinds registered