Logs

The logging system captures server-side activity into an in-memory ring buffer with REST and SSE streaming access. Logs are ideal for debugging extensions, cron jobs, and API calls without needing external log aggregation.

Log Entry Structure


interface LogEntry {
  id: string;              // Unique entry ID
  timestamp: string;       // ISO timestamp
  level: 'debug' | 'info' | 'warn' | 'error';
  source: 'extension' | 'api' | 'emitter' | 'database' | 'auth' | 'system';
  message: string;
  data?: Record<string, any>;  // Optional structured data
  extensionId?: string;
  extensionName?: string;
  collection?: string;
  requestId?: string;
  userId?: string;
}

Configuration

Environment variable	Default	Description
`LOG_MAX_ENTRIES`	`1000`	Ring buffer size
`LOG_MIN_LEVEL`	`debug`	Minimum log level (`debug`, `info`, `warn`, `error`)
`LOG_CONSOLE_OUTPUT`	`true`	Also write to stdout

REST API

Get logs


GET /api/logs

Query parameters:

Parameter	Description	Example
`limit`	Number of entries to return (default: 50, max: 500)	`?limit=100`
`level`	Filter by level	`?level=error`
`source`	Filter by source	`?source=extension`
`extensionId`	Filter by extension UUID	`?extensionId=<uuid>`
`extensionName`	Filter by extension name (partial match)	`?extensionName=slug`
`collection`	Filter by collection	`?collection=articles`
`since`	Entries after this timestamp or relative time (`1h`, `30m`, `1d`)	`?since=2025-01-01T00:00:00Z`
`until`	Entries before this timestamp	`?until=2025-01-02T00:00:00Z`
`search`	Text search in message	`?search=validation`

Response:


{
  "data": {
    "count": 1,
    "entries": [
      {
        "id": "log-uuid",
        "timestamp": "2025-01-15T10:00:00Z",
        "level": "error",
        "source": "extension",
        "message": "Validation failed: title is required",
        "extensionName": "article-validator",
        "collection": "articles"
      }
    ]
  }
}

Clear logs


DELETE /api/logs

Clears all log entries from the in-memory buffer. Requires admin access.

Stream logs (SSE)


GET /api/logs/stream

Returns a text/event-stream response. Each new log entry is pushed as a Server-Sent Event. Supports level, source, and extensionName query parameters for filtering.


const es = new EventSource('/api/logs/stream?level=error', {
  headers: { Authorization: `Bearer ${token}` },
});
 
es.onmessage = (event) => {
  const entry = JSON.parse(event.data);
  console.log(entry.message);
};

MCP Tool

The logs MCP tool exposes log access to AI agents:


// Tail the last 50 entries
{ "action": "tail", "lines": 50, "level": "error" }
 
// Read with filters
{ "action": "read", "since": "2025-01-15T00:00:00Z", "source": "extension" }
 
// Search log messages
{ "action": "search", "query": "validation failed", "source": "extension" }
 
// Get buffer statistics
{ "action": "stats" }
 
// Clear all logs (admin only)
{ "action": "clear" }

The log buffer is in-memory and is cleared on server restart. For persistent log storage, forward logs to an external service using an action hook on the system.log event or by tailing the SSE stream.