Pionia Docs v3 Get started

Developer stats & metrics

This guide is for DeskFlow developers who want visibility into API usage — slow task.list calls, OPcache hit rate, and framework health at /stats on port 8000.

What you will learn

  • How to open /stats and /stats.json with a token when DEBUG=false
  • What php pionia stats:view prints from storage/metrics/requests.jsonl
  • How OPcache snapshots feed Production performance
Before you start
  • DeskFlow running (php pionia serve or runserver)
  • Familiarity with Logging — complementary, not a replacement

How it works

flowchart LR API[POST /api/v1/ task.*] --> Metrics[Request metrics writer] Metrics --> File[storage/metrics/requests.jsonl] File --> Web[/stats + /stats.json] File --> CLI[php pionia stats:view] Workers[RoadRunner workers] --> Snap[opcache-snapshot.json] Snap --> Preload[optimize:preload --snapshot]

Pionia records per-request metrics for Moonlight API calls and exposes them through a web dashboard and CLI.

Web dashboard

URLFormat
/statsHTML health dashboard
/stats.jsonSame data as JSON

Enabled when DEBUG=true by default, or explicitly:

# environment/settings.ini
STATS_ENABLED = true
# environment/.env — generate your own token; never commit a shared docs example
STATS_TOKEN=

Generate a token locally (Security utilities):

php pionia shell
secure_random_hex(32); // paste into STATS_TOKEN= in environment/.env

Access the dashboard with ?token=<your-token> or header X-Stats-Token: <your-token>.

Lock down production

Disable stats in production or require a strong STATS_TOKEN. Do not leave /stats open without authentication when DEBUG=false.

CLI snapshot

php pionia stats:view              # human-readable table
php pionia stats:view --json       # JSON export
php pionia stats:view --reset      # clear storage/metrics/requests.jsonl

Aliases: stats, viewstats.

Disabling writes

To stop writing metrics while keeping the stats page:

[metrics]
ENABLED = false

What is collected

  • Request count, average duration, slow endpoints
  • Grouping by service/action where applicable
  • Framework static assets (/__pionia/*) are excluded
  • OPcache — hit rate, cached scripts, preload memory, JIT status
  • Framework version — resolved from installed pionia/pionia-core Composer package

When [performance] RECORD_OPCACHE_SNAPSHOT=true, workers also write storage/metrics/opcache-snapshot.json for stats-driven preload generation (see Production performance).

Common mistakes

  • Leaving /stats public in production — set STATS_TOKEN or disable with STATS_ENABLED=false.
  • Using stats as audit logging — metrics are aggregated; use Logging for per-request detail.
  • Resetting metrics during an investigation — stats:view --reset clears history; export with --json first.
  • Expecting static asset hits in API metrics — /__pionia/* routes are excluded from Moonlight grouping.

What’s next

Production performance

optimize --production and preload.

Logging

logger(), report(), storage/logs/.

HTTP routing

Bootstrap route cache.

Last updated on July 4, 2026
Edit this page on GitHub
Prev
Documenting your API (Moonlight)
Next
HTTP routing