Logs & observability

OrbitNest records a structured log entry for SQL statements, end-user auth events and edge function executions in every project. Browse them in the Studio Logs tab, or query them over the REST API and the MCP server.

What gets logged

Each entry in the main project log has an event_type, a log_level, an event_subtype (a short message such as operation_executed), a timestamp and a metadata object.

Table-data reads and row create, update and delete endpoints (what the SDK query builders use) are not logged individually. Storage operations are not logged.

The log schema also accepts the debug level and a system event type, but nothing writes them today.

Per-type detail

Each type also keeps a detailed record that the type-specific views and endpoints return:

• Database: the SQL text, table name, operation type (SELECT, INSERT, CREATE_TABLE, ...), rows affected, execution time in ms, success flag, and any error message.
• Auth: the project's own auth audit log, stored in the project database. It covers every sign-in method, including password, SMS and MFA. Its event_type values are listed in Auth events.
• Edge functions: status (success, error or timeout), duration, request method and path, response status, error message and stack, and a cold-start flag. Console output (console.log, info, warn and error) is stored per execution.

Redaction

Before SQL text is stored, OrbitNest masks values assigned to names like password, secret, token or key, and string literals that contain those words or an email address. Stored SQL is cut off at 2,000 characters. Line breaks and control characters in IP addresses and user agents are replaced with spaces.

Auth events

The Auth view reads these event_type values from the project's auth audit log:

Logs in Studio

Open a project and select Logs. Use the view menu in the header to switch between views:

The header also has:

• Search: type a term and press Enter.
• Filters: event type, log level, and a start and end date. Filters and search apply to the All Logs view.
• Refresh: reloads the current view.
• Export: downloads JSON or CSV.

Click the eye icon on a row to open its details: message, SQL, metadata, and IDs such as user, request and execution ID.

Search and filters

The main log endpoint accepts these query parameters:

curl "https://api.orbitnest.io/api/projects/$PROJECT_ID/logs?level=error&event_type=database&search=posts&limit=50" \
  -H "Authorization: Bearer $ORBITNEST_ADMIN_TOKEN"

{
  "success": true,
  "data": [
    {
      "id": "5b1e…",
      "log_level": "error",
      "event_type": "database",
      "event_subtype": "operation_executed",
      "source_table": "posts",
      "operation_type": "SELECT",
      "duration_ms": 4,
      "error_message": "column \"titel\" does not exist",
      "metadata": { "sql_query": "SELECT titel FROM posts", "rows_affected": 0 },
      "created_at": "2026-10-10T09:14:03.120Z"
    }
  ],
  "total": 1,
  "has_more": false,
  "limit": 50,
  "offset": 0,
  "filters": { "level": ["error"], "event_type": "database", "search": "posts", "limit": 50 }
}

total is the exact number of entries that match the filters across all pages. has_more is true when entries remain after this page. Page through results with offset.

A failed query returns a 5xx error, not 400. 400 is only for invalid parameters.

REST endpoints

All paths are relative to https://api.orbitnest.io/api/projects/:projectId/logs.

Every list endpoint accepts limit (1–1000, default 100) and offset, and returns the same envelope as the main log, with an exact total and has_more. An unknown query parameter returns 400.

On /auth:

• success=false returns events whose type contains fail, and success=true the rest. The auth audit log has no separate success column.
• search matches the event type and the event traits, case-insensitively. Separate several terms with |, as in search=failed|locked, to match any of them.
• ip_address matches the client IP exactly.

function_name on /edge-functions matches the function name case-insensitively.

Slow queries

GET /database/slow returns database statements whose execution time was over 1,000 ms, newest first. The threshold is applied in the query, so paging with limit and offset reaches every slow statement on record, not only recent ones. GET /database?slow_query=true does the same. Each record includes the SQL text, table, operation type, rows affected and execution_time_ms.

curl "https://api.orbitnest.io/api/projects/$PROJECT_ID/logs/database/slow?limit=500" \
  -H "Authorization: Bearer $ORBITNEST_ADMIN_TOKEN"

Execution plans are not captured. To investigate a slow statement, run EXPLAIN ANALYZE on it in the SQL editor.

Log stats

GET /stats returns all-time counts from the main project log. If the counts can't be read, it returns 500 rather than zeros.

{
  "total": 18234,
  "by_level": { "info": 17410, "warn": 512, "error": 312 },
  "by_event_type": [
    { "type": "database", "count": 15020 },
    { "type": "edge_function", "count": 2702 },
    { "type": "auth", "count": 512 }
  ]
}

Export

GET /export downloads up to the 10,000 most recent matching entries of the main project log as a file named logs-<projectId>-<date>.json or .csv. When the export hits that cap, the response has the header X-Export-Truncated: true; narrow the time range to get the rest.

Export accepts every parameter the list endpoints accept, so you can pass your current view's filters. limit and offset are ignored, and parameters the main log doesn't use, such as table_name, have no effect.

curl -OJ "https://api.orbitnest.io/api/projects/$PROJECT_ID/logs/export?format=csv&event_type=edge_function&start_time=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $ORBITNEST_ADMIN_TOKEN"

In CSV exports, objects are written as JSON. Cells starting with =, +, -, @, a tab or a carriage return get a leading ' so spreadsheet apps don't run them as formulas.

Function logs

Each function also has its own log, with console output attached to every execution. In Studio, open the function under Functions and select the Logs tab. Over the API, use GET /api/projects/:projectId/functions/:name/logs?limit=50. See Edge functions for details.

Logs from the MCP server

The MCP server exposes the log endpoints as tools. Each tool uses the active project unless you pass a projectId.

Data lifetime

Log entries are deleted with their project. The auth audit log lives in the project database and is removed when the project is deleted. No automatic time-based retention is configured for logs, so export what you need for long-term analysis.