# Yii2 application logging

Backend, API v1, and Console share `common\\log\\LoggingConfig` and `common\\log\\JsonFileTarget`. They write to their independent `@runtime/logs` directories: `backend/runtime/logs`, `api/v1/runtime/logs`, and `console/runtime/logs`.

Each project writes `error.log`, `warning.log`, `info.log`, and `debug.log`. Yii error, warning, info, trace, and profile levels are routed to exactly one file; trace and profile share `debug.log`. Each line is one JSON object. The stable `category` is `application`; `source_category` preserves Yii's original category.

Files rotate at 20 MiB by default and retain 14 rotated files. Override with `YII_LOG_MAX_FILE_SIZE_KB` and `YII_LOG_MAX_FILES`. Yii rotates by copy and truncate to keep the active filename stable for tailing. New log files use mode 0640 and directories use 0750. Deployment must ensure PHP and Console share a writable group. Startup does not change ownership or existing directory permissions.

API logs contain a validated incoming `X-Request-ID` or a generated ID, HTTP method, request path without query string, response status, elapsed time, and user ID when available. IP is included only when `YII_DEBUG` is enabled. Console logs contain command, execution ID, elapsed time, and status. Explicit credential fields (password, token, API key, authorization) in free-form messages are redacted.

The API Apache VirtualHost writes server logs to `api/v1/runtime/logs/apache-error.log` and `apache-access.log`. Those use Apache's native formats. Runtime directories are outside the configured document roots. The Apache VirtualHosts also deny access to the backend and API log paths if later exposed through an Alias. The Console path is outside both web roots. Nginx or another server needs an equivalent deny rule.

## Alloy and Loki

Tail these paths (or deployment-mounted equivalents):

```text
/path/to/ikiwae/backend/runtime/logs/{error,warning,info,debug}.log
/path/to/ikiwae/api/v1/runtime/logs/{error,warning,info,debug}.log
/path/to/ikiwae/console/runtime/logs/{error,warning,info,debug}.log
```

Parse each line as JSON and promote only bounded `project`, `level`, and `environment` fields to Loki labels. Keep request ID, execution ID, user ID, path, and IP as JSON fields. Ensure the Alloy setup follows rotated files and does not define duplicate sources for these paths.

```logql
{project="backend", level="error"}
{project="api", level="error"}
{project="console", level="error"}
```

## Manual verification

In development, emit `Yii::error('sample error', 'logging-check')`, `Yii::warning('sample warning', 'logging-check')`, `Yii::info('sample info', 'logging-check')`, and `Yii::debug('sample debug', 'logging-check')`. Confirm each JSON record appears only in its matching file and includes timestamp, level, project, environment, category, and message. Send an API request with `X-Request-ID: check-123` and confirm the ID appears. Run a console command and confirm command and execution ID fields. Tail the directories with the deployment Alloy agent and verify one stream per source and only the three bounded labels. Do not use real credentials when checking redaction.

Some existing developer log directories have permissive modes. Review `stat` or `ls -ld` on the deployment host and set owner, group, and mode through deployment configuration so PHP and Console can write without granting unrelated users access. Do not use 0777 in production.
