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 to 1.
  • pageSize (optional): The number of logs per page. Defaults to 50.
  • 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. page is at least 1; pageSize is clamped to 1–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"
}