Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ ClawShell supports OAuth-based authentication as an alternative to static API ke

ClawShell exposes running counters at `GET /admin/stats` so operators can audit proxy activity since startup and across restarts.

- **What's Counted**: Total requests served, total upstream `prompt_tokens` / `completion_tokens` / `total_tokens` (parsed from non-streaming JSON responses — SSE streams are not counted), number of emails hidden by the sender policy, and a per-address breakdown of filtered senders.
- **What's Counted**: Total requests protected, total upstream `prompt_tokens` / `completion_tokens` / `total_tokens` (parsed from non-streaming JSON responses — SSE streams are not counted), number of emails hidden by the sender policy, and a per-address breakdown of filtered senders.
- **Loopback-Only**: The endpoint is reachable without a virtual key but only from `127.0.0.1` / `::1` peers; non-loopback clients receive `403`.
- **Persistent**: Counters are flushed to disk every 30 seconds and on graceful shutdown. The location is a required config field — set `[stats] persist_path = "..."` in `clawshell.toml` (typically `/var/lib/clawshell/stats.json` under the hardened systemd unit, since `/etc/clawshell` is read-only there).
- **Bounded**: The filtered-address map is capped at 10,000 unique entries; further unique addresses are aggregated under an `<overflow>` bucket so memory stays bounded.
Expand Down
2 changes: 1 addition & 1 deletion clawshell.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ patterns = [
]

# Runtime statistics persistence
# ClawShell counts total requests served, upstream prompt/completion/total
# ClawShell counts total requests protected, upstream prompt/completion/total
# tokens (from non-streaming responses), and per-sender email-filter
# activity, and exposes them at GET /admin/stats (loopback-only).
[stats]
Expand Down
4 changes: 2 additions & 2 deletions src/onboard/skills.rs
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ curl -sS "{base_url}/admin/stats"

After the request succeeds, present a short human-readable summary:

1. Total requests served and total tokens (prompt + completion + combined).
1. Total requests protected and total tokens (prompt + completion + combined).
2. Email-filter activity: the total filtered count, plus the top 5 addresses
by per-address count.
3. If the `filtered_email_addresses` map contains the synthetic key
Expand Down Expand Up @@ -237,7 +237,7 @@ curl -sS "{base_url}/admin/stats"

## Full response schema

- `requests_total` (u64): every request that reached the axum router,
- `requests_total` (u64): every request protected by ClawShell,
regardless of status code. Includes both the proxy catch-all and the
`/v1/email/*` routes (and this `/admin/stats` route itself).
- `prompt_tokens_total` (u64): sum of upstream `prompt_tokens` /
Expand Down
2 changes: 1 addition & 1 deletion src/onboard/types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ pub const STATS_CRON_JOB_NAME: &str = "clawshell-weekly-stats";
pub const STATS_CRON_PROMPT: &str = "\
Use the get-clawshell-stats skill to fetch ClawShell runtime statistics \
from the /admin/stats endpoint, then present a short summary: total \
requests served, token usage (prompt, completion, total), and \
requests protected, token usage (prompt, completion, total), and \
email-filter activity (total filtered count plus the top filtered \
senders). If the endpoint returns an error or is unreachable, report \
that instead.";
Expand Down
Loading