Logs
The agent on each server tails your apps’ logs and ships them to Loki with the site’s labels. You read them in the service panel, the CLI, the API or Grafana. Logs need the observability stack.
What is collected
Section titled “What is collected”| Source | Collected from | Notes |
|---|---|---|
| Laravel / Statamic | shared/storage/logs/*.log |
Multi-line records (stack traces) are merged into one entry |
| Symfony | shared/var/log |
|
| Other PHP apps | the site’s shared log directory | |
| Web processes, workers, daemons, Horizon, Octane | program output (/var/log/falak) |
|
| Cron jobs and the scheduler | job output | |
| Docker and compose containers | container output (stdout / stderr), labelled with the Compose service | |
| Files inside containers | the paths you add under Sources | See Files inside containers (v0.15.0) |
| PHP-FPM | the error log of a site’s own PHP-FPM master, and the slow-request log | See PHP-FPM logs (v0.15.0) |
| Edge requests | /var/log/falak/access/<site>.log |
Shown as Network logs, falak_log_kind="access" |
| Deployments | lifecycle events from the control plane and agents | |
| Database instances | engine output and slow queries | See Database observability (v0.16.0) |
Multi-line Laravel records start with [YYYY-MM-DD HH:MM:SS; continuation lines are merged until the next record (capped at 256 KiB per record).
Files inside containers
Section titled “Files inside containers”A Docker or compose app often writes its logs to files inside the container (storage/logs/laravel.log, an nginx error log). Site → Logs → Sources lets you add up to 10 of them per site.
| Field | Rule |
|---|---|
| Path | An absolute path or glob inside the container, such as /var/www/html/storage/logs/*.log. No .., nothing under /proc, /sys or /dev, up to 255 bytes. *, ? and [...] work in any segment. |
| Format | plain (default) or json (one object per line; message, level, time and trace ids are extracted) |
| Multi-line | None, Laravel (records start with [YYYY-MM-DD HH:MM:SS), or a start pattern: a regular expression a record’s first line matches; other lines join the record before them |
| Service | Compose sites: only that service’s containers (empty: every service) |
How the agent reads them:
- From the host, through the container’s own root. No
docker exec, nothing installed in the image. - Reads stay inside the container’s root, refuse
/proc,/sys,/dev, kernel filesystems, devices and pipes, and only ever open regular files. Scanning, reading and open files are capped per site, so one site can’t slow log shipping for the others. - It keeps its place across agent restarts and log rotation. A container created by a deploy is read from the start of its files, so the first lines aren’t lost.
- A log symlinked to
/dev/stdout(as official nginx images do) is skipped: it is already in the container’s output.
Container sources need agent feature logs.container_files (v0.15.0); older agents never receive them. Sources are set in the UI and API, not in falak.yaml yet.
PHP-FPM logs
Section titled “PHP-FPM logs”For native PHP-FPM sites:
- Error log. A site with its own PHP-FPM master (a site with resource limits) ships that master’s error log: worker crashes,
max_childrenreached, output a worker wrote to stderr. - Slow requests. PHP-FPM writes a stack trace of every request that runs longer than the threshold. New PHP-FPM sites start at 5 seconds; sites created before v0.15.0 stay off until you set it under Sources (1–600 s, 0 or empty = off). Changing it re-sends the site’s pool to its servers.
Falak rotates both logs daily (7 files, 50 MB). The slow log needs agent feature runtime.fpm.slowlog.
Laravel exceptions become Issues
Section titled “Laravel exceptions become Issues”For Laravel log files (host or container), an ERROR, CRITICAL, ALERT or EMERGENCY entry with an exception and a stack trace opens or updates an Issue, without the APM package. It is grouped like an APM exception (class plus top in-app frames), so the same error reported both ways lands in the same Issue.
- A site that also runs the APM package gets each exception once: a log exception is dropped only when the APM reported the same exception (same class and first in-app frame) within a minute. Exceptions the APM never sees (Horizon and queue supervisors, artisan commands,
Log::error($e)) still arrive (v0.16.1). - At most 120 log-derived exceptions per site per minute are sent.
- Laravel’s default log line has no time zone; Falak reads it as UTC.
- Laravel’s JSON log format is not parsed for exceptions.
Read logs
Section titled “Read logs”Service panel → Logs: live stream with search, level, server and source filters, pause/follow. Click a line to open its trace. Observability → Logs searches across sites.
The source filter shows the options that apply to the site’s runtime: Output (stdout / stderr), App log files, Container files, PHP-FPM, Slow requests and Access (edge).

falak logs shop # last hour, up to 200 linesfalak logs shop --since 6h --level errorfalak logs shop -f # follow, polls every 2 sfalak --json logs shop -f | jq .message # NDJSONcurl "https://falak.example.com/api/v1/sites/shop/logs?since=3600&limit=100&level=error&kind=app" \ -H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json"{"data": [{"at": "2026-09-26T10:00:02.000000+00:00", "level": "ERROR", "source": "laravel", "server": "web-1", "message": "boom", "attributes": {"service_name": "laravel"}}], "meta": {"cursor": "1790000000000000001"}}See Logs API.
Filters
Section titled “Filters”| Filter | Values |
|---|---|
since |
Seconds back (API, default 3600, up to 30 days) or a duration (CLI, 30m, 6h) |
level |
trace, debug, info, warn, error, fatal |
kind |
app (files, programs, cron, containers) or access (edge requests); default both |
limit |
1–1000 per page (API), default 100; CLI default 200 |
cursor |
Continue from the previous page |
In Grafana
Section titled “In Grafana”{service_name="shop", falak_log_kind="app"} |= "SQLSTATE"{service_name="shop", falak_log_kind="access"} | json | status >= 500sum by (falak_server_id) (count_over_time({service_name="shop"} |= "ERROR" [5m]))Troubleshooting
Section titled “Troubleshooting”| Symptom | Fix |
|---|---|
Logs tab empty, API 503 |
The observability stack is not enabled or Loki is down (falak-ctl status). |
| Web request logs missing for a Laravel site | LOG_CHANNEL is stderr; set daily and redeploy. |
Permission denied on laravel.log |
Deploy again; writable directories get group-writable default ACLs so FrankenPHP and workers can share the file. |