Hannibal Smith
34898b1196
- analyze.js: burn rate, weekly reconstruction, cycle stagger, rotation rank, underspend alerts, log prune with weekly archive - logger.js: getCachedRun(maxAgeMinutes) — skip probing if recent data exists - monitor.js: cache guard at wake — 20-min dedup, zero extra API calls - test.js: fix type assertion for gemini-api/xai-api providers (+5 passing); add 14 new tests for cache guard and analyze.js (162 total, all green) - docs/analyze.md: usage reference Co-authored-by: Hannibal Smith <hannibal@trentuna.com>
54 lines
2.2 KiB
Markdown
54 lines
2.2 KiB
Markdown
# analyze.js — Token Monitor Analysis CLI
|
||
|
||
Reads accumulated JSONL logs from `~/.logs/token-monitor/` and produces burn
|
||
rates, weekly stats, reset schedule, and rotation recommendations.
|
||
|
||
## Usage
|
||
|
||
```
|
||
node analyze.js # full report (default)
|
||
node analyze.js --burn-rate # burn rate per account only
|
||
node analyze.js --weekly # weekly budget reconstruction
|
||
node analyze.js --stagger # reset schedule (next 48h)
|
||
node analyze.js --rotation # rotation recommendation only
|
||
node analyze.js --json # JSON output (all sections)
|
||
node analyze.js --provider team-nadja # filter to one provider
|
||
node analyze.js --prune # prune logs older than 30 days
|
||
node analyze.js --prune --dry-run # dry run — show what would be pruned
|
||
```
|
||
|
||
## Output sections
|
||
|
||
**Burn Rate** — delta analysis of 7d utilization over time, projected
|
||
exhaustion at current rate. Requires ≥ 2 data points per provider.
|
||
|
||
**Reset Schedule** — providers resetting within the next 48 hours, sorted
|
||
ascending by time to reset.
|
||
|
||
**Weekly Reconstruction** — peak and average 7d utilization per provider per
|
||
ISO week. Shows exhaustion events (status=rejected).
|
||
|
||
**Rotation Recommendation** — ranked provider list. Rules in priority order:
|
||
1. Invalid key → bottom (unusable)
|
||
2. Maxed/rejected → deprioritize; soonest reset wins tiebreaker
|
||
3. Dormant → reserve for cycle staggering
|
||
4. Active: rank by headroom (1 - utilization_7d)
|
||
|
||
**Underspend Alerts** — active accounts with ≥ 40% of 5h window unused and
|
||
< 2h until reset. These tokens expire unused — boost them.
|
||
|
||
## Log format
|
||
|
||
Input: `~/.logs/token-monitor/YYYY-MM-DD.jsonl` — one JSON object per line.
|
||
|
||
Pruned archives: `~/.logs/token-monitor/weeks/YYYY-WNN.json` — weekly
|
||
aggregates with peak/avg utilization and sample counts.
|
||
|
||
## Cadence
|
||
|
||
Logs are written by `monitor.js` at each Vigilio wake (max once per 20
|
||
minutes — cache guard prevents double-logging within a session). Expected:
|
||
~15–20 data points/day per active provider, ~100–140/week.
|
||
|
||
At target cadence, log footprint is < 1MB/month. --prune trims files older
|
||
than 30 days after archiving them into weekly summaries.
|