Skip to content

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.

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).

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.

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_children reached, 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.

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.

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).

Observability → Logs: log lines from all sites with level, site and server columns and a search field.

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
LogQL examples
{service_name="shop", falak_log_kind="app"} |= "SQLSTATE"
{service_name="shop", falak_log_kind="access"} | json | status >= 500
sum by (falak_server_id) (count_over_time({service_name="shop"} |= "ERROR" [5m]))
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.