Skip to main content

Observability

Register metrics and health endpoints in bootstrap.php. The application template enables /health by default.

use Omnitrix\Config\Env;
use Omnitrix\Security\BearerTokenAuth;
use Omnitrix\Security\Identity;

$app->enableMetrics('/metrics', [
new BearerTokenAuth(fn (string $t): ?Identity => hash_equals(Env::required('METRICS_TOKEN'), $t) ? new Identity('prometheus') : null),
]);
$app->health('/health'); // /health/live and /health/ready (database and Redis checks when configured)
  • Request counters and latency histograms are kept in shared memory, so any worker serves server-wide numbers in Prometheus text format. Labels: route pattern (never the raw path), method, status.
  • Gauges: connections, requests, coroutines, event-loop lag (current/max/avg), worker memory, idle workers, and the serving worker's database, Redis and HTTP client pool statistics.
  • Readiness runs all checks concurrently with a timeout (default 2 s); failures report the exception class only. Add your own checks with health('/health', ['search' => fn (): bool => ...]).

Logging​

The default logger writes one JSON object per line to stderr, at app.log_level and above. $app->logger() returns it; pass any PSR-3 logger to Application::create($config, $logger) in bootstrap.php to replace it. To log to a file:

use Omnitrix\Core\Log\JsonLogger;

$app = Application::create($config, new JsonLogger(fopen('/var/log/api/app.log', 'ab')));

Point logs at a file or a collector that always drains them: a stderr pipe that nobody reads blocks workers once the pipe buffer (typically 64 KiB) is full.

Access logs​

use Omnitrix\Observability\AccessLog;

$app->middleware(new AccessLog($app->logger(), skipPaths: ['/health/live']));

One JSON line per request: method, route pattern, path, status, duration, request id and client address. Query strings, headers and bodies are never logged.

Request ids​

Every response carries X-Request-Id, and error bodies include request_id. Log lines written while handling a request contain the same id, so a client-visible error can be traced to the log. Read it in code with $request->id().