Skip to content

Collector configuration

phpray-collector is a small Go daemon that reads the trace stream from shared memory (or the file path), stores it, applies retention/alerts and serves the local API + dashboard. Config file: /etc/phpray/collector.toml (override with --config).

collector.toml

[reader]
# Where the extension writes.
mode = "shm"                    # "shm" | "file"
shm_path = "/dev/shm/phpray"
file_path = "/var/lib/phpray/traces"
batch_ms = 500

[storage]
# Local SQLite database for traces, aggregates and dashboards.
path = "/var/lib/phpray/phpray.db"

[retention]
# How long different data lives in SQLite.
traces_days = 14                # full traces
aggregates_days = 90            # per-minute aggregates
max_mb = 4096                   # hard cap: oldest rows pruned beyond this

[alerts]
# Inbound alert rules (consumed by the extension's crash_threshold/window).
enabled = true
webhook = ""                    # optional outgoing webhook URL

[api]
# Local dashboard + JSON API (used by `phpray` CLI).
bind = "127.0.0.1:9191"

[auth]
# Bearer token for the API; the CLI reads the same file.
jwt_secret = "change-me"
tokens_path = "/etc/phpray/tokens.json"

[cloud]
# Optional: outbound ingest to PHPRay Cloud (see ../cloud/ingest.md).
server_key = "prk_<32 hex>"
endpoint = "https://ingest.phpray.dev"
buffer.max_mb = 32              # local spool when the console is unreachable
privacy.mask_host = false       # per-server default; per-site in the console
traces.sample_rate = 100        # percent; console may lower it via /v1/control

Comments in the file mirror this; every key is optional except [reader] and [storage].

Running it

systemctl enable --now phpray-collector
systemctl status phpray-collector
phpray status          # one-line view: collector, shm, dashboard, cloud

Logs

  • journald: journalctl -u phpray-collector
  • file fallback (only if journald unavailable): /var/log/phpray/collector.log
  • trace storage: /var/lib/phpray/phpray.db (SQLite, one file)
  • raw file-mode traces (if output_mode=file): /var/lib/phpray/traces/*.jsonl

Disk limits

The collector enforces [retention].max_mb (default 4 GB) as a hard cap on the SQLite file: when the file exceeds it, oldest rows are pruned until it fits again. Retention windows (traces_days, aggregates_days) prune independently, whichever hits first. The cloud spool is separately capped by [cloud].buffer.max_mb (default 32 MB) and drops oldest traces, never aggregates.