Proxy Logs

The Proxy Logs API provides centralized access to request, response, and event logs produced by the Hoody proxy. Use these endpoints to search historical logs, retrieve aggregate statistics, and stream new entries in real time over Server-Sent Events.

Query Centralized Logs

GET /_logs

Search and filter through the stored request/response and event logs. Results are scoped to the authenticated project by default; admin callers can opt into cross-tenant fanout using the cursor parameter when LOGS_ADMIN_FANOUT=true.

Note

Scoped reads return JSON. Admin fanout (LOGS_ADMIN_FANOUT=true) returns NDJSON streaming with a final {"__trailer": true, "cursor": "...", "stoppedReason": "..."} line.

Parameters

Name	In	Type	Required	Description
limit	query	integer	No	Maximum entries to return. Default: 200.
offset	query	integer	No	Number of entries to skip. Default: 0.
projectId	query	string	No	Filter to a single project.
containerId	query	string	No	Filter to a single container.
serviceName	query	string	No	Filter to a single service.
level	query	string	No	Comma-separated levels (debug,info,warn,error).
includeRequestBody	query	boolean	No	Include the request body in entries. Default: false.
includeResponseBody	query	boolean	No	Include the response body in entries. Default: false.
last	query	integer	No	Return only the last N entries.
afterId	query	integer	No	Return entries with SQLite row ID greater than this (ASC cursor).
cursor	query	string	No	v8 §5.2 — cross-tenant fanout pagination cursor (signed opaque base64). Only honored when LOGS_ADMIN_FANOUT=true.
kind	query	string	No	One of: request, response, event.
method	query	string	No	Filter by HTTP method.
source	query	string	No	One of: backend, edge.

Example Request

cURL

curl -X GET "https://api.hoody.com/_logs?limit=200&containerId=cnt_def456&level=info,warn&kind=request" \
  -H "Authorization: Bearer <token>"

SDK

const iterator = await client.proxyLogs.logs.listIterator({
  limit: 200,
  containerId: "cnt_def456",
  level: "info,warn",
  kind: "request"
});

for await (const entry of iterator) {
  console.log(entry.tsIso, entry.level, entry.method, entry.url);
}

Response

200

{
  "entries": [
    {
      "id": 12345,
      "traceId": "550e8400-e29b-41d4-a716-446655440000",
      "tsMs": 1705312200000,
      "tsIso": "2024-01-15T12:30:00.000Z",
      "kind": "request",
      "level": "info",
      "projectId": "proj_abc123",
      "containerId": "cnt_def456",
      "serviceName": "api-gateway",
      "method": "GET",
      "url": "/v1/users",
      "clientIp": "192.168.1.100",
      "status": 200,
      "data": {},
      "source": "edge"
    }
  ],
  "total": 1500,
  "limit": 200,
  "offset": 0
}

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions to access logs"
}

410

Fanout snapshot expired. The client must restart the scan without a cursor.

{
  "__trailer": true,
  "error": "snapshot_expired",
  "status": 410
}

Get Log Statistics

GET /_logs/stats

Retrieve aggregate counts for stored logs, broken down by level, project, container, and service.

This endpoint takes no parameters.

Example Request

cURL

curl -X GET "https://api.hoody.com/_logs/stats" \
  -H "Authorization: Bearer <token>"

SDK

const stats = await client.proxyLogs.logs.getStats();
console.log(stats.total, stats.byLevel);

Response

200

{
  "total": 125000,
  "byLevel": {
    "debug": 45000,
    "info": 60000,
    "warn": 15000,
    "error": 5000
  },
  "byProject": {
    "proj_abc123": 75000,
    "proj_def456": 50000
  },
  "byContainer": {
    "cnt_111": 40000,
    "cnt_222": 35000,
    "cnt_333": 50000
  },
  "byService": {
    "api-gateway": 80000,
    "auth-service": 25000,
    "db-proxy": 20000
  }
}

Stream Live Logs

GET /_logs/stream

Opens a persistent Server-Sent Events connection that streams new log entries as they are recorded by the proxy.

Note

v8 §6.4 framing — every frame carries an id: <ringSeq> line followed by a JSON-serialized data: payload:

id: 12345
data:

Periodic :\n\n heartbeats every 15 seconds keep the connection alive.

Tip

Reconnect resume — clients may send Last-Event-ID: <ringSeq> on reconnect. The server skips any frame whose ringSeq is less than or equal to that value from the ring buffer (5000 entries / ~50 s replay window at 100 entries/s).

Caution

Named events (v8):

• event: scope-destroyed — container destroyed; the stream closes immediately after. Clients should exit cleanly.
• event: reset — server restart; the ringSeq counter is reset with a ≥10 000 safety margin. Clients MUST discard their lastSeenId and reconnect fresh.

Parameters

Name	In	Type	Required	Description
projectId	query	string	No	Filter to a single project (admin-port only; SNI clients are auto-scoped).
containerId	query	string	No	Filter to a single container.
kind	query	string	No	One of: request, response, event.
level	query	string	No	One of: debug, info, warn, error.
Last-Event-ID	header	string	No	v8 §6.4 — numeric ringSeq of the last event received. Server skips entries ≤ this value from the ring buffer on reconnect.

Example Request

cURL

curl -X GET "https://api.hoody.com/_logs/stream?containerId=cnt_def456&level=info" \
  -H "Authorization: Bearer <token>" \
  -H "Last-Event-ID: 12345" \
  -H "Accept: text/event-stream"

SDK

const stream = await client.proxyLogs.logs.streamLogs({
  containerId: "cnt_def456",
  level: "info"
});

stream.on("event", (event) => {
  if (event.event === "scope-destroyed") {
    stream.close();
    return;
  }
  if (event.event === "reset") {
    // Discard lastSeenId and reconnect fresh.
    stream.close();
    return;
  }
  console.log("id:", event.id, "data:", event.data);
});

Response

200

SSE stream of live log entries. Each frame carries an id: line with the ringSeq and a data: line with a JSON-serialized LogEntry.

id: 12346
data: {"id":12346,"traceId":"550e8400-e29b-41d4-a716-446655440000","tsMs":1705312201000,"tsIso":"2024-01-15T12:30:01.000Z","kind":"event","level":"info","projectId":"proj_abc123","containerId":"cnt_def456","serviceName":"api-gateway","method":"POST","url":"/v1/orders","clientIp":"192.168.1.100","status":201,"data":{},"source":"backend"}

:

403

Logs token missing or invalid / SNI gate denied.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Logs token missing or invalid"
}

429

Rate limited.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}