LogService: Query, Stream, and Clear FrostAgent Logs

LogService exposes the in-memory log ring buffer that FrostAgent writes to at runtime. The buffer holds up to 5,000 entries and is initialised at startup; once full, the oldest entries are overwritten by new ones. The service is accessible at /frostagent.v1.LogService/ and provides three RPCs: ListLogs for paginated queries, StreamLogs for a live feed of new entries, and ClearLogs to flush the buffer.

Log levels

Log level values map to the LogLevel enum in the protobuf definition. Use numeric or string values in JSON requests.

Name	Value	Description
`LOG_LEVEL_UNSPECIFIED`	`0`	Unset; matches all levels when used as `min_level`
`LOG_LEVEL_DEBUG`	`1`	Verbose diagnostic output
`LOG_LEVEL_INFO`	`2`	Normal operational messages
`LOG_LEVEL_WARN`	`3`	Non-fatal warnings
`LOG_LEVEL_ERROR`	`4`	Errors that require attention

Log sources

Each log entry carries a source string derived from the internal Category type. Use these exact strings in source_filter to narrow results.

Source	Typical content
`SYSTEM`	Engine lifecycle events — startup, shutdown, initialisation
`HTTP`	Inbound HTTP requests and outbound HTTP responses
`TOOL`	Tool invocations and their results
`WEBSOCKET`	OneBot WebSocket connection and message events
`LLM_REQUEST`	Outbound prompts sent to the upstream LLM provider
`LLM_RESPONSE`	Raw responses received from the upstream LLM provider

ListLogs

Returns a paginated, timestamp-descending snapshot of log entries from the ring buffer. Optional filters narrow results by minimum severity level and source category. Request: ListLogsRequest

pagination

Pagination

Controls which page of results to return.

Show Pagination fields

min_level

LogLevel

Only return entries at or above this severity level. Omit or set to 0 (LOG_LEVEL_UNSPECIFIED) to return all levels.

source_filter

string

Only return entries whose source matches this string exactly, e.g. "LLM_REQUEST". Omit or set to "" to return all sources.

Response: ListLogsResponse

entries

repeated LogEntry

Log entries for the requested page, sorted by timestamp descending (most recent first).

Show LogEntry fields

string

A unique entry identifier derived from the entry’s UnixNano timestamp, e.g. "1717228022123456789".

timestamp

string

RFC 3339 Nano timestamp of when the entry was recorded, e.g. "2025-06-01T11:47:02.123456789Z".

level

LogLevel

Severity level as a numeric enum value.

source

string

The category that emitted this entry, e.g. "SYSTEM" or "LLM_RESPONSE".

summary

string

The human-readable log message content.

has_detail

bool

true when summary is non-empty, indicating there is readable detail to display.

request_body

string

Reserved for a future raw request payload field. Always returns an empty string in the current release — the log service does not populate this field.

response_body

string

Reserved for a future raw response body field. Always returns an empty string in the current release — the log service does not populate this field.

pagination

Pagination

Pagination metadata. total is the filtered entry count; page_token is the cursor for the next page, or "" on the last page.

Example — fetch the 20 most recent error logs

curl -X POST http://localhost:8080/frostagent.v1.LogService/ListLogs \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": { "page_size": 20 },
    "min_level": 4,
    "source_filter": ""
  }'

{
  "entries": [
    {
      "id": "1717228022123456789",
      "timestamp": "2025-06-01T11:47:02.123456789Z",
      "level": 4,
      "source": "HTTP",
      "summary": "upstream returned 502: bad gateway",
      "has_detail": true,
      "request_body": "",
      "response_body": ""
    }
  ],
  "pagination": {
    "page_size": 20,
    "page_token": "",
    "total": 1
  }
}

StreamLogs

A server-streaming RPC that pushes new LogEntry messages to the client as they are emitted by the engine. The stream remains open until the client disconnects or the server is shut down. Filters work identically to ListLogs — entries that do not match are dropped before being sent. Request: StreamLogsRequest

min_level

LogLevel

Minimum severity level to stream. Defaults to all levels if omitted.

source_filter

string

Exact source name to filter by. Omit or set to "" to stream all sources.

Response stream: LogEntry Each streamed message has the same fields as documented in ListLogs above. Example — stream all LLM request/response entries

curl -X POST http://localhost:8080/frostagent.v1.LogService/StreamLogs \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "min_level": 2,
    "source_filter": "LLM_REQUEST"
  }'

ConnectRPC server-streaming responses use HTTP chunked transfer encoding. Pass --no-buffer with curl, or use a ConnectRPC-aware client library for the best experience.

ClearLogs

Flushes the in-memory ring buffer by replacing it with a fresh, empty ring of the same capacity (5,000). Entries are gone immediately and cannot be recovered. Request: ClearLogsRequest No fields. Send {}. Response: ClearLogsResponse

success

bool

Always true when the operation completes. The buffer is unconditionally reset.

Example

curl -X POST http://localhost:8080/frostagent.v1.LogService/ClearLogs \
  -H "Content-Type: application/json" \
  -d '{}'

{ "success": true }

All logs are stored in memory only and are lost when FrostAgent restarts. The ring buffer holds a maximum of 5,000 entries; older entries are silently overwritten as new ones arrive. If you need persistent log storage, consider forwarding log output from stdout to an external collector.

ConnectRPC Services

HTTP Endpoints

LogService: Query, Stream, and Clear FrostAgent Logs

Log levels

Log sources

ListLogs

StreamLogs

ClearLogs

Build docs developers (and LLMs) love

ConnectRPC Services

HTTP Endpoints

Documentation Index

​Log levels

​Log sources

​ListLogs

​StreamLogs

​ClearLogs

Build docs developers (and LLMs) love

Log levels

Log sources

ListLogs

StreamLogs

ClearLogs