Debugger API

The Debugger API provides tools for inspecting the event pipeline — trace events, debug routing decisions, test subscription filters, and replay historical events.

Query Traces

GET /api/debugger/traces?topic=session.status&source=database&limit=50&offset=0

Query Parameters:

Param	Required	Description
`topic`	No	Filter by topic
`source`	No	Filter by source (`database`, `sync`, `socket`)
`limit`	No	Max results (default 50)
`offset`	No	Pagination offset

Response:

[
  {
    "traceId": "trace_abc123",
    "eventId": "evt_a1b2c3d4",
    "topic": "session.status",
    "source": "database",
    "type": "database.update",
    "payload": { "sessionId": "abc123", "status": "active" },
    "timestamp": 1710000000000,
    "routingResult": {
      "subscriberCount": 3,
      "deliveredCount": 3,
      "filteredCount": 0
    }
  }
]

Get Trace Detail

GET /api/debugger/traces/:traceId

Returns the full trace including routing decisions, filter results, and delivery status.

Debug Routing

Test how an event would be routed without actually publishing it:

POST /api/debugger/debug-routing

Request Body:

{
  "event": {
    "topic": "session.status",
    "source": "database",
    "type": "database.update",
    "payload": { "sessionId": "abc123", "status": "active" }
  }
}

Response:

{
  "topic": "session.status",
  "activeSubscriptions": 5,
  "matchingSubscriptions": 3,
  "routingDetails": [
    { "subscriptionId": "sub_1", "matched": true, "filter": { "campusId": 12 } },
    { "subscriptionId": "sub_2", "matched": false, "filter": { "campusId": 99 } }
  ]
}

Debug Filter

Test a specific filter against an event:

POST /api/debugger/debug-filter

Request Body:

{
  "event": {
    "topic": "session.status",
    "payload": { "sessionId": "abc123", "status": "active", "campusId": 12 }
  },
  "filter": {
    "campusId": 12,
    "status": { "in": ["active", "pending"] }
  }
}

Response:

{
  "matched": true,
  "details": {
    "campusId": { "matched": true, "expected": 12, "actual": 12 },
    "status": { "matched": true, "expected": ["active", "pending"], "actual": "active" }
  }
}

Replay Event

Replay a historical event from the trace store:

POST /api/debugger/replay

Request Body:

{
  "traceId": "trace_abc123",
  "mode": "dry-run",
  "overrides": {
    "payload": { "status": "ended" }
  }
}

Replay Modes:

Mode	Description
`dry-run`	Simulate routing without delivery
`router`	Re-route through the event router
`websocket`	Re-deliver to WebSocket subscribers
`webhook`	Re-deliver to webhook endpoints

Warning

Replay with websocket or webhook mode delivers real events to subscribers. Use with caution. Requires elevated permissions.