Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Logs and bugs logs

kater logs audit

Runs a report on the calls that agents made to Kater's tools.

Use it to see what an agent did in a conversation, which calls failed, or which calls were slow. You need the audit:read permission. See Users.

Examples

Terminal window
# List the recent agent threads, to find a thread's id
kater logs audit recent_threads
# Show every call in one thread, by its id from recent_threads
kater logs audit thread_history --thread 123e4567-e89b-12d3-a456-426614174000
# List the calls that failed for one person
kater logs audit recent_errors --user teammate@example.com
# List the calls that took 5 seconds or more, slowest first
kater logs audit slow_calls --minimum-duration-ms 5000
# Count the calls and the errors of each tool
kater logs audit tool_usage

Arguments

ArgumentDescription
<template-name>The report to run: recent_threads, thread_history, recent_errors, tool_usage or slow_calls. See The reports.

Options

OptionDescription
--parameters <json>The report’s parameters as a JSON object, such as {"user_email": "teammate@example.com"}. The keys are audit_thread_id, user_email and minimum_duration_ms. You cannot use it with --parameters-file.
--parameters-file <file>The report’s parameters, from a JSON file. Give - to read stdin.
--thread <id>One agent thread, by the id that recent_threads gives. thread_history needs it.
--user <email>One person’s calls, by their Kater email.
--minimum-duration-ms <n>With slow_calls, only the calls that took at least this many milliseconds.
--cursor <cursor>The next_cursor of the page before, to read the next page.
--limit <n>The most rows on one page, from 1 to 1,000, 100 by default. tool_usage does not use it.

It also takes the global options --json, --kater-root, --scope and --help.

The reports

ReportWhat it listsNarrow it with
recent_threadsThe agent threads, the latest updated first, each with its id. Threads with no calls come last.--user
thread_historyEvery call in one thread.--thread, which it needs
recent_errorsThe calls that did not succeed, newest first.--thread, --user
tool_usageFor each tool, how many calls and errors it had, and its average and longest time. It is one page, with no --cursor.--thread, --user
slow_callsThe calls, slowest first.--thread, --user, --minimum-duration-ms

Each call gives its tool, its arguments, its result, its status and error, when it started and ended, and how long it took. Kater refuses a parameter that the report does not take, and a parameter that you give two times.

Where the audit is kept

In your own terminal, the audit is .kater/audit.sqlite3 in your content root, or the file that KATER_AUDIT_DB_PATH names. On Kater’s servers, each organization reads its own audit.

See also