Health checks and troubleshooting

When a site misbehaves there are four places to look, in this order: the doctor, which checks the host and the install from a shell; the Health page, which checks the running application; the logs; and the table of symptoms at the end of this page. Most faults an operator meets are in that table.

Run the doctor#

From the site's directory:

php glueful thallo:doctor

It prints one row per check — OK, WARN or FAIL — and ends with a styled box: the environment looks healthy, or some checks failed. The command's exit status follows: a FAIL fails it, and --strict makes a WARN fail it too, which is what a deploy script wants.

Three of those rows are conditional. environment, asset-routing and api-routing need a .env to read. The two routing probes run only when BASE_URL names a public host — localhost, 127.0.0.1, ::1, 0.0.0.0 and any host ending in .localhost, .local or .test are treated as local and skipped — and they give no verdict at all when the host cannot be reached from the machine you run the command on. The database row appears only once the database is configured in .env.

theme-vocabulary checks the theme chosen on the Appearance page when the database can be reached, and the one RENDER_THEME names in .env otherwise; the row says which it checked. A chosen theme that no longer loads does not take the site down: the site serves the RENDER_THEME theme until you fix it or choose another, and the row says so.

Read the Health page#

Utilities › Health reports on the application as it runs. It needs the system.access permission. Refresh re-runs every check.

The page opens with an overall status — ok, warning or error — then lists the checks, each with its own status and message, and any issues, warnings and recommendations the check produced.

The overall status counts every check, the scheduler's included: error when any check errs, warning when any warns. The config check's recommendations are different — a wildcard CORS_ALLOWED_ORIGINS, an empty CSP_HEADER, no HSTS_HEADER, LOG_LEVEL=debug — they are listed but never change the status.

Below the checks, System gives the Thallo version (or "development checkout"), the newest published version when the update check has run, the framework version, the environment, the PHP version, memory used against the limit, peak memory, free disk against total, and the time the report was taken.

Find the logs#

Logs are files under storage/logs/. LOG_FILE_PATH in .env moves the directory.

The three dated files rotate daily and LOG_ROTATION_DAYS (30) of them are kept. The scheduler's and the worker's own output goes wherever their cron line or unit sends it; see the scheduler and the queue.

How much is written is set by LOG_PROFILE, which falls back to APP_ENV. The production profile logs the framework channel at warning and the application channel at warning; development logs info and debug. FRAMEWORK_LOG_LEVEL and LOG_LEVEL override the profile one channel at a time, and APP_DEBUG=true forces the framework channel down to debug whatever else is set. Turn a level up to reproduce a fault, and turn it back down: debug logging on a live site fills a disk.

Who changed what is not in these files. Users & Access › Audit Log holds that.

Clear a cache, and when that is the answer#

Utilities › Cache shows the driver, the key prefix, whether tag invalidation is on, the key count and whatever statistics the driver exposes. It offers two actions. Clear one content type invalidates just that type's delivery cache. Clear all cache flushes every entry on the instance and asks you to confirm first; pages and queries are recomputed on next access.

From a shell, four commands clear four different things:

php glueful cache:status and php glueful cache:inspect only read.

Clearing a cache is rarely the answer to stale content. Publishing, unpublishing, deleting and changing a content type all purge the affected pages by tag as they happen, and on a driver that cannot invalidate tags — the default file driver — the whole rendered-page cache is dropped instead. Changing the appearance, a menu, a region, a style class or a template through the admin purges too. What none of that covers is a change made to a theme's files on disk: after a deploy that edits templates or theme CSS, run render:cache:clear. A Redis-backed cache survives a restart, so restarting PHP is not a way to clear it.

Symptoms and their usual causes#

Confirm the site is healthy#

• php glueful thallo:doctor --strict exits without failing.
• Utilities › Health shows an overall status of ok, and the scheduler check is ok too.
• The site answers 200 for /theme-assets/site.css?t=default and for a page, and the admin loads at /admin.

If a fault survives all of that, gather the failing request's entry from storage/logs/, the doctor's table and the Health page's checks before you ask for help: they are what anyone diagnosing it will want first.