System Logs API
This section describes the API endpoints for managing and retrieving system event logs. These endpoints require administrator authentication.
Admin Endpoints (Requires Authentication)
List Logs
Retrieve a paginated list of system logs.
Endpoint: GET /api/admin/logs
Query Parameters:
page(optional): The page number to retrieve. Defaults to1.pageSize(optional): The number of logs per page. Defaults to50.search(optional): Search the message and details for a request ID, error message or pathname (up to 200 characters). Pagination applies to the filtered results.pageis at least1;pageSizeis clamped to1–100.
Response:
{
"logs": [
{
"id": 1,
"level": "error",
"message": "Payment gateway timeout",
"details": "{\"error\": \"Connection refused\", \"gateway\": \"stripe\"}",
"source": "payment",
"createdAt": "2024-01-01T12:00:00.000Z"
}
],
"total": 150,
"page": 1,
"pageSize": 50
}
Diagnosing HTTP 5xx and runtime errors
Every request receives a generated x-request-id response header. Error JSON also contains requestId; object-valued data includes the same ID while preserving business error fields. A 5xx message includes [requestId], so existing API error notifications can display it. Fatal/unhandled messages remain sanitized in production. HTML 500/503 pages show a copyable request ID, path and build version; development additionally shows the error stack.
Open Admin → Logs → System and search for this ID, or use GET /api/admin/logs?search=<requestId>. HTTP 5xx records use source http-error; failures without an HTTP event use runtime-error. Details include UTC time, build ID, method, pathname, status, duration, user ID (when available), stack and a bounded cause chain. The detail dialog renders stacks and causes on separate lines. These records reuse the existing logs table and administrator permissions; no schema migration is needed.
Evidence is also written to the server console ([api-error]) and, on Node deployments, ${APAY_DATA_DIR:-.data}/logs/api-errors.jsonl, with a 5 MiB rotation threshold. File writes are asynchronous so a busy disk does not stall other requests. Page 404s (non-/api paths, mostly crawler probes) are not recorded; API 404s still are. Console/file logging runs before database logging, so database outages remain diagnosable. Edge deployments use platform console logs rather than local files. Request bodies, cookies, headers and query strings are not recorded; URL credentials and query strings, SQL parameter lines and common credential assignments in error messages are redacted. Treat remaining diagnostics as administrator-only data.
Server source maps are bundled with the server; retain server .map files when packaging. Start Node with node --enable-source-maps .output/server/index.mjs (or add --enable-source-maps to NODE_OPTIONS) to map even modules loaded before the error plugin initializes. The plugin enables mapping for subsequently loaded modules as a fallback. Node source-map behavior. Client source maps remain disabled. Logging failures never change the original HTTP outcome. Rollback is a code rollback; there are no data migrations or business retries. Import/startup failures before plugins initialize and errors swallowed inside business code still require process/platform logs. Browser-only failures are visible in the development console, but are not uploaded to the server.
Delete a Log
Delete a specific log entry by its ID.
Endpoint: DELETE /api/admin/logs/:id
Response:
{
"success": true
}
Clear All Logs
Permanently delete all system logs.
Endpoint: DELETE /api/admin/logs/clear
Response:
{
"success": true,
"message": "All logs cleared successfully"
}