3d87c04d20
- Add docs/architecture.md with 4 mermaid diagrams - Add docs/mitm.md with 3 mermaid diagrams (replaces mitm-interception-status) - Add docs/traces.md documenting per-call trace system - Rewrite README.md to be concise with mermaid and doc refs - Rewrite GEMINI.md for core philosophy and agent usage - Clean extension-server-analysis.md (remove stale debug sections) - Delete temp docs: standalone-ls-todo, panel-stream-investigation, endpoint-gap-analysis, request-comparison
119 lines
3.1 KiB
Markdown
119 lines
3.1 KiB
Markdown
# Trace System
|
|
|
|
Per-call debug traces for inspecting request/response flow. Every API call writes a structured trace directory.
|
|
|
|
## Location
|
|
|
|
```
|
|
~/.config/antigravity-proxy/traces/{YYYY-MM-DD}/{HH-MM-SS.sss}_{cascade_short}/
|
|
```
|
|
|
|
Disable with `--no-trace`.
|
|
|
|
## Files Per Trace
|
|
|
|
| File | Purpose |
|
|
| --------------- | ---------------------------------------------------------- |
|
|
| `meta.txt` | One-line grep-friendly summary |
|
|
| `summary.md` | Human-readable trace overview with tables |
|
|
| `request.json` | Client request metadata (message count, preview, tools) |
|
|
| `response.json` | Token usage (input, output, thinking, cache) |
|
|
| `turns.json` | Per-turn details (MITM match, gate wait, response preview) |
|
|
|
|
## Data Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant H as API Handler
|
|
participant T as TraceHandle
|
|
participant D as Disk
|
|
|
|
H->>T: trace.start(cascade_id, endpoint, model)
|
|
H->>T: set_client_request(preview, tool_count, ...)
|
|
Note over H: Request processing...
|
|
H->>T: start_turn()
|
|
H->>T: record_mitm_match(gate_wait_ms)
|
|
Note over H: Response arrives...
|
|
H->>T: record_response(text_len, preview, finish_reason)
|
|
H->>T: set_usage(input, output, thinking, cache)
|
|
H->>T: finish("completed")
|
|
T->>D: Write meta.txt, summary.md, request.json, response.json, turns.json
|
|
```
|
|
|
|
## Example: meta.txt
|
|
|
|
```
|
|
cascade=e57e3ddf endpoint=POST gemini model=gemini-3-flash outcome=completed duration=1865ms stream=false
|
|
```
|
|
|
|
## Example: request.json
|
|
|
|
```json
|
|
{
|
|
"message_count": 2,
|
|
"tool_count": 3,
|
|
"tool_round_count": 0,
|
|
"user_text_len": 46,
|
|
"user_text_preview": "You are a pirate.\n\nSay ahoy in exactly 3 words",
|
|
"system_prompt": true,
|
|
"has_image": false
|
|
}
|
|
```
|
|
|
|
## Example: turns.json
|
|
|
|
```json
|
|
[
|
|
{
|
|
"turn": 0,
|
|
"mitm_matched": true,
|
|
"gate_wait_ms": 90,
|
|
"response": {
|
|
"text_len": 18,
|
|
"thinking_len": 0,
|
|
"text_preview": "Ahoy there, matey!",
|
|
"finish_reason": "stop",
|
|
"grounding": false
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
## Example: response.json
|
|
|
|
```json
|
|
{
|
|
"usage": {
|
|
"input_tokens": 284,
|
|
"output_tokens": 13,
|
|
"thinking_tokens": 37,
|
|
"cache_read": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
## Outcomes
|
|
|
|
| Outcome | When |
|
|
| ---------------- | --------------------------------- |
|
|
| `completed` | Normal response received |
|
|
| `tool_call` | Model returned function calls |
|
|
| `upstream_error` | Google API returned an error |
|
|
| `timeout` | No response within timeout window |
|
|
| `mitm_timeout` | MITM gate match timed out |
|
|
|
|
## Agent Usage
|
|
|
|
Traces are designed for LLM consumption. To inspect the last trace:
|
|
|
|
```bash
|
|
# Find latest trace
|
|
ls -t ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/ | head -1
|
|
|
|
# Read the summary
|
|
cat ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/$(ls -t ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/ | head -1)/summary.md
|
|
|
|
# Grep for failures
|
|
grep 'outcome=.*error\|outcome=.*timeout' ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/*/meta.txt
|
|
```
|