Script Kit Logging
Structured logging patterns for debugging and observability.
AI Compact Log Mode (SCRIPT_KIT_AI_LOG=1)
Compact stderr format: SS.mmm|L|C|message
L: i INFO, w WARN, e ERROR, d DEBUG, t TRACEC categories:
P position, A app, U UI, S stdin, H hotkeyV visibility, E exec, K key, F focus, T themeC cache, R perf, W window_mgr, X errorM mouse_hover, L scroll_state, Q scroll_perfD design, B script, N config, Z resize
Example:
- Standard:
... INFO ... Selected display origin=(0,0)
- Compact:
13.150|i|P|Selected display origin=(0,0)
Enable:
SCRIPT_KIT_AI_LOG=1 ./target/debug/script-kit-gpui 2>&1
Log Modes
| Mode |
Command |
Use Case |
| Compact AI logs |
SCRIPT_KIT_AI_LOG=1 |
Default for AI agents (saves ~70% tokens) |
| Full debug logs |
RUST_LOG=debug |
Deep debugging |
| Specific module |
RUST_LOG=script_kit::theme=debug |
Target one module |
JSONL Logging
Logs to: ~/.scriptkit/logs/script-kit-gpui.jsonl
Line example:
{"timestamp":"...","level":"INFO","target":"script_kit::executor","message":"Script executed","fields":{"script_name":"hello.ts","duration_ms":142,"exit_code":0}}
Tracing Patterns
Use tracing + tracing-subscriber:
#[instrument] for spans- Record
duration_ms; warn if slow (e.g. >100ms)
Correlation IDs:
- Generate UUID per user action/run
- Attach to spans so nested logs inherit it
Required fields when relevant: correlation_id, duration_ms, bead_id, agent_name, files_touched
Log Level Guide
error: failurewarn: unexpected but handledinfo: key eventsdebug: developmenttrace: very verbose
Filter by targets (module paths): script_kit::ui, script_kit::executor, script_kit::theme
Error Handling
- Application errors:
anyhow::Result; add .context() at boundaries
- Domain/library errors:
thiserror when callers match variants
- User-facing errors:
NotifyResultExt → log first (tracing::error!) then toast
Best practices:
- Don't
unwrap()/expect()
- Add context at each level ("which file?", "what operation?")
- Use typed fields in logs (avoid interpolated strings)
Log Queries
grep '"correlation_id":"abc-123"' ~/.scriptkit/logs/script-kit-gpui.jsonl
grep '"duration_ms":' ~/.scriptkit/logs/script-kit-gpui.jsonl | jq 'select(.fields.duration_ms > 100)'
grep '"level":"ERROR"' ~/.scriptkit/logs/script-kit-gpui.jsonl | tail -50
1---2name: script-kit-logging3description: Logging and observability patterns for Script Kit GPUI. Use when adding logs, debugging, or understanding the logging system. Covers JSONL format, compact AI log mode, correlation IDs, and error handling.4---5
6# Script Kit Logging
7
8Structured logging patterns for debugging and observability.
9
10## AI Compact Log Mode (SCRIPT_KIT_AI_LOG=1)
11
12Compact stderr format: `SS.mmm|L|C|message`
13
14- `L`: `i` INFO, `w` WARN, `e` ERROR, `d` DEBUG, `t` TRACE
15- `C` categories:
16 - `P` position, `A` app, `U` UI, `S` stdin, `H` hotkey
17 - `V` visibility, `E` exec, `K` key, `F` focus, `T` theme
18 - `C` cache, `R` perf, `W` window_mgr, `X` error
19 - `M` mouse_hover, `L` scroll_state, `Q` scroll_perf
20 - `D` design, `B` script, `N` config, `Z` resize
21
22Example:
23- Standard: `... INFO ... Selected display origin=(0,0)`
24- Compact: `13.150|i|P|Selected display origin=(0,0)`
25
26Enable:
27```bash
28SCRIPT_KIT_AI_LOG=1 ./target/debug/script-kit-gpui 2>&1
29```
30
31## Log Modes
32
33| Mode | Command | Use Case |
34|------|---------|----------|
35| Compact AI logs | `SCRIPT_KIT_AI_LOG=1` | Default for AI agents (saves ~70% tokens) |
36| Full debug logs | `RUST_LOG=debug` | Deep debugging |
37| Specific module | `RUST_LOG=script_kit::theme=debug` | Target one module |
38
39## JSONL Logging
40
41Logs to: `~/.scriptkit/logs/script-kit-gpui.jsonl`
42
43Line example:
44```json
45{"timestamp":"...","level":"INFO","target":"script_kit::executor","message":"Script executed","fields":{"script_name":"hello.ts","duration_ms":142,"exit_code":0}}
46```
47
48## Tracing Patterns
49
50Use `tracing` + `tracing-subscriber`:
51- `#[instrument]` for spans
52- Record `duration_ms`; warn if slow (e.g. >100ms)
53
54Correlation IDs:
55- Generate UUID per user action/run
56- Attach to spans so nested logs inherit it
57
58Required fields when relevant: `correlation_id`, `duration_ms`, `bead_id`, `agent_name`, `files_touched`
59
60## Log Level Guide
61
62- `error`: failure
63- `warn`: unexpected but handled
64- `info`: key events
65- `debug`: development
66- `trace`: very verbose
67
68Filter by targets (module paths): `script_kit::ui`, `script_kit::executor`, `script_kit::theme`
69
70## Error Handling
71
72- Application errors: `anyhow::Result`; add `.context()` at boundaries
73- Domain/library errors: `thiserror` when callers match variants
74- User-facing errors: `NotifyResultExt` → log first (`tracing::error!`) then toast
75
76Best practices:
77- Don't `unwrap()`/`expect()`
78- Add context at each level ("which file?", "what operation?")
79- Use typed fields in logs (avoid interpolated strings)
80
81## Log Queries
82
83```bash
84grep '"correlation_id":"abc-123"' ~/.scriptkit/logs/script-kit-gpui.jsonl
85grep '"duration_ms":' ~/.scriptkit/logs/script-kit-gpui.jsonl | jq 'select(.fields.duration_ms > 100)'
86grep '"level":"ERROR"' ~/.scriptkit/logs/script-kit-gpui.jsonl | tail -50
87```
majiayu000