Logging

Every call, model turn, tool invocation, and webhook delivery emits a structured JSON log line. Read them in the dashboard, query them by field, or stream them to your own log platform.

Log structure

{
  "ts": "2026-08-02T15:07:41.284Z",
  "level": "info",
  "source": "tool",
  "workspace_id": "ws_42",
  "agent_id": "agt_123",
  "call_id": "cl_889",
  "trace_id": "tr_5f2c",
  "event": "tool.completed",
  "tool": "book_appointment",
  "duration_ms": 412,
  "status_code": 200
}

Sources

Levels

• debug — Per-turn detail including partial transcripts. Off by default; enable per agent while investigating.
• info — Normal operation. Everything a healthy call emits.
• warn — Recovered problems — a fallback fired, a retry succeeded, a tool was slow.
• error — Something failed and affected the call. These drive alerts.

Querying

Open Data → Logs and filter by any field. Queries support equality, negation, and ranges, and every result links back to the call it belongs to.

source:tool status_code:>=400 last:24h
agent_id:agt_123 event:pipeline-error-llm last:7d
level:warn -tool:check_calendar last:1h

Trace IDs

Every call gets a trace_id shared by all its log lines across sources. Pass it through to your own systems — it is sent on webhooks as x-katexs-trace-id — so a customer complaint can be resolved end to end from one identifier.

Export and retention

{
  "log_export": {
    "type": "https",
    "url": "https://logs.example.com/ingest/katexs",
    "auth": { "type": "bearer", "secret_ref": "LOG_SINK_KEY" },
    "format": "ndjson",
    "sources": ["call", "tool", "webhook"],
    "min_level": "info"
  }
}