Skip to content

monitoring.md

Latest commit

 

History

History
115 lines (81 loc) · 6.95 KB

monitoring.md

File metadata and controls

115 lines (81 loc) · 6.95 KB
Raw

Monitoring & Diagnostics

The preload interceptor includes monitoring for several issues identified by the community. These features work in preload mode (CC ≤v2.1.112). The proxy mode provides cache telemetry via the cache-telemetry extension; other monitoring features below are preload-specific.

Microcompact / budget enforcement

Claude Code silently replaces old tool results with [Old tool result content cleared] via server-controlled mechanisms (GrowthBook flags). A 200,000-character aggregate cap and per-tool caps (Bash: 30K, Grep: 20K) truncate older results without notification. There is no DISABLE_MICROCOMPACT environment variable.

The interceptor detects cleared tool results and logs counts. When total tool result characters approach the 200K threshold, a warning is logged.

False rate limiter

The client can generate synthetic "Rate limit reached" errors without making an API call, identifiable by "model": "<synthetic>". The interceptor logs these events.

GrowthBook flag dump

On the first API call, the interceptor reads ~/.claude.json and logs the current state of cost/cache-relevant server-controlled flags (hawthorn_window, pewter_kestrel, slate_heron, session_memory, etc.).

Quota tracking

Response headers are parsed for anthropic-ratelimit-unified-5h-utilization and 7d-utilization, saved to ~/.claude/quota-status.json for consumption by status line hooks or other tools. This works in both proxy mode (via cache-telemetry extension) and preload mode.

Peak hour detection

Anthropic applies elevated quota drain rates during weekday peak hours (13:00–19:00 UTC, Mon–Fri). The interceptor detects peak windows and writes peak_hour: true/false to quota-status.json. See docs/peak-hours-reference.md for sources and details.

Usage telemetry and cost reporting

The interceptor logs per-call usage data to ~/.claude/usage.jsonl — one JSON line per API call with model, token counts, and cache breakdown. Use the bundled cost report tool to analyze costs:

node tools/cost-report.mjs                    # today's costs from interceptor log
node tools/cost-report.mjs --date 2026-04-08  # specific date
node tools/cost-report.mjs --since 2h         # last 2 hours
node tools/cost-report.mjs --admin-key <key>  # cross-reference with Admin API

Also works with any JSONL containing Anthropic usage fields (--file, stdin) — useful for SDK users and proxy setups. See docs/cost-report.md for full documentation.

Quota analysis (5-hour quota counting)

The same usage.jsonl log can be analyzed to test how Anthropic's 5-hour quota is actually computed. Run the bundled tool:

node tools/quota-analysis.mjs              # analyze your default log
node tools/quota-analysis.mjs --since 24h  # last 24 hours only
node tools/quota-analysis.mjs --json       # machine-readable output

The tool answers three questions from your own data:

  1. Does cache_read count toward your 5-hour quota? Tests three hypotheses (cache_read costs 0x / 0.1x / 1x of input rate) and reports which one best explains your q5h_pct trajectory across reset windows.
  2. Do peak hours cost more quota per token? Splits windows into peak-dominant (≥80% peak calls) and off-peak-dominant (≤20%) and compares the implied 100% quota.
  3. What is your account's effective 5-hour quota in token-equivalents? Reports a concrete number you can compare against your subscription tier.

Requires q5h_pct, q7d_pct, and peak_hour fields in usage.jsonl, which were added in v1.6.1 (2026-04-09).

Help us validate across accounts: if you run this on your own log, please open an issue or PR with your output. Cross-validating across multiple accounts is the only way to distinguish per-account variance from real findings. Reference: anthropics/claude-code#45756.

Debug mode

Enable debug logging to verify the fix is working:

CACHE_FIX_DEBUG=1 claude-fixed

Logs are written to ~/.claude/cache-fix-debug.log. Look for:

  • APPLIED: resume message relocation — block scatter was detected and fixed
  • APPLIED: tool order stabilization — tools were reordered
  • APPLIED: fingerprint stabilized from XXX to YYY — fingerprint was corrected
  • APPLIED: stripped N images from old tool results — images were stripped
  • APPLIED: output efficiency section rewritten — output-efficiency section was replaced
  • MICROCOMPACT: N/M tool results cleared — microcompact degradation detected
  • BUDGET WARNING: tool result chars at N / 200,000 threshold — approaching budget cap
  • FALSE RATE LIMIT: synthetic model detected — client-side false rate limit
  • GROWTHBOOK FLAGS: {...} — server-controlled feature flags on first call
  • PROMPT SIZE: system=N tools=N injected=N (skills=N mcp=N ...) — per-call prompt size breakdown
  • CACHE TTL: tier=1h create=N read=N hit=N% (1h=N 5m=N) — TTL tier and cache hit rate per call
  • PEAK HOUR: weekday 13:00-19:00 UTC — Anthropic peak hour throttling active
  • SKIPPED: resume relocation (not a resume or already correct) — no fix needed
  • SKIPPED: output efficiency rewrite (section not found) — no matching output-efficiency section found

Prefix diff mode

Enable cross-process prefix snapshot diffing to diagnose cache busts on restart:

CACHE_FIX_PREFIXDIFF=1 claude-fixed

Snapshots are saved to ~/.claude/cache-fix-snapshots/ and diff reports are generated on the first API call after a restart.

Environment variables (preload mode)

Proxy mode uses extension configuration in proxy/extensions.json. These env vars apply to the preload interceptor.

Variable Default Description
CACHE_FIX_DEBUG 0 Enable debug logging to ~/.claude/cache-fix-debug.log
CACHE_FIX_PREFIXDIFF 0 Enable prefix snapshot diffing
CACHE_FIX_IMAGE_KEEP_LAST 0 Keep images in last N user messages (0 = disabled)
CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT unset Replace Claude Code's # Output efficiency system-prompt section
CACHE_FIX_USAGE_LOG ~/.claude/usage.jsonl Path for per-call usage telemetry log
CACHE_FIX_DISABLED 0 Disable all bug fixes; keep monitoring + optimizations active
CACHE_FIX_SKIP_RELOCATE 0 Skip block relocation fix
CACHE_FIX_SKIP_FINGERPRINT 0 Skip fingerprint stabilization
CACHE_FIX_SKIP_TOOL_SORT 0 Skip tool ordering stabilization
CACHE_FIX_SKIP_TTL 0 Skip TTL injection
CACHE_FIX_SKIP_IDENTITY 0 Skip identity normalization
CACHE_FIX_SKIP_GIT_STATUS 0 Skip git-status stripping
CACHE_FIX_STRIP_GIT_STATUS 0 Strip volatile git-status from system prompt
CACHE_FIX_TTL_MAIN 1h TTL for main-thread requests: 1h, 5m, or none
CACHE_FIX_TTL_SUBAGENT 1h TTL for subagent requests: 1h, 5m, or none
CACHE_FIX_DUMP_BREAKPOINTS unset Path to dump cache breakpoint structure (diagnostic for #12)