From 6ce4c656bd41f95df2ca47db6050c5d1c63495c6 Mon Sep 17 00:00:00 2001 From: ADD-SP Date: Sun, 12 Apr 2026 10:21:27 -0700 Subject: [PATCH] fix: rename "requests served" to "requests protected" in stats reporting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ClawShell is a security proxy — "protected" better describes what the request counter represents. Updated in the skill SKILL.md, the reference API doc, the cron job prompt, the example config, and the README. --- README.md | 2 +- clawshell.example.toml | 2 +- src/onboard/skills.rs | 4 ++-- src/onboard/types.rs | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 8579edf..ceddd1b 100644 --- a/README.md +++ b/README.md @@ -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 `` bucket so memory stays bounded. diff --git a/clawshell.example.toml b/clawshell.example.toml index 73d3773..b97d379 100644 --- a/clawshell.example.toml +++ b/clawshell.example.toml @@ -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] diff --git a/src/onboard/skills.rs b/src/onboard/skills.rs index b36cc55..aa89b6e 100644 --- a/src/onboard/skills.rs +++ b/src/onboard/skills.rs @@ -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 @@ -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` / diff --git a/src/onboard/types.rs b/src/onboard/types.rs index a0949b3..57aea56 100644 --- a/src/onboard/types.rs +++ b/src/onboard/types.rs @@ -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.";