# Logging

## Where logs go

Application logs are written by the file logger into `storage/`. That directory is not web-accessible: in the document-root-at-`public/` layout it sits outside the web root, and in the everything-in-`public_html` layout the shipped `.htaccess` blocks it.

**Verify this after installing.** A readable log file is an information disclosure, and it ships with a protection precisely because it matters.

## What gets logged

| Level | Used for |
|---|---|
| error | Caught exceptions: failed queries, failed mail, failed plugin load, failed widget render, API failures |
| warning | Degraded conditions: sitemap truncation at the URL cap, recoverable configuration problems |

Each entry carries a timestamp, a message, and structured context — a route, a method, an identifier.

## What is never logged

- SMTP passwords, Telegram bot tokens, Turnstile secrets, API tokens
- Raw provider response bodies that could contain credentials
- Member passwords or reset tokens in any form

This is a rule, not a default. When adding a log line, check what your context array actually contains.

## Reading a failure

Most user-visible failures are deliberately soft:

| Symptom | Log entry to look for |
|---|---|
| Home feed empty but the site works | `Homepage community feed query failed.` |
| A sidebar region is missing | `Homepage widget rendering failed.` |
| Mail silently not arriving | Mailer errors, plus the staged test result |
| A plugin feature stopped working | The plugin load or handler error |
| Sitemap missing URLs | The sitemap URL-limit warning, with the limit named |

The page stays up in each of these cases. The log is the only place the failure is recorded, which is why an unread log is a broken monitoring strategy.

## Rotation

There is no built-in rotation — no cron is required to run Quaeriva, so nothing rotates by itself. On a busy site, rotate `storage/` logs with the host's tooling, or truncate them as part of routine maintenance.

## PHP errors

In production, display errors off and log errors on. A stack trace rendered to a visitor discloses paths and code structure. Quaeriva renders a translated error page instead; the detail belongs in the log.

## During development

Run `php -S 127.0.0.1:8003 -t public public/router.php` and watch the console alongside the file log. See [Local development](../LOCAL-DEVELOPMENT.md).
