Logging

Chaz uses the tracing crate for structured logging. Default verbosity is info.

Where Logs Go

The sink depends on the gateway mode, because the TUI and print modes need to keep stdout clean for their own output:

Mode	Default destination
TUI (default)	<state_dir>/chaz-tui.log (daily-rotated, keeps 7 days)
-p / --print	<state_dir>/chaz-cli.log (daily-rotated, keeps 7 days)
--no-tui	stdout (collected by systemd / docker / your supervisor)
chaz usage (CLI)	stderr (stdout is the rollup output)

Background gateways (today: Matrix when configured alongside the TUI) log to the same destination as the foreground TUI — the TUI grabs stdout, so everything in-process goes to the rotated file.

state_dir comes from state_dir: in the config or the platform XDG state dir (typically ~/.local/state/chaz). The startup banner prints the exact log path for the TUI/print cases. Tail with tail -f <state_dir>/chaz-tui.log.

Controlling Verbosity

Set the RUST_LOG environment variable:

# Default: info level and above
chaz --config config.yaml

# Debug: detailed operational info (tool results, LLM traffic)
RUST_LOG=debug chaz --config config.yaml

# Errors only
RUST_LOG=error chaz --config config.yaml

# Per-module filtering
RUST_LOG=chaz_core::runtime=debug,chaz_core::security=warn chaz --config config.yaml

What Gets Logged

info (default)

At the default level you'll see:

• Startup: config loaded, agent count, tool registry ready, gateway mode, eidetica sync address
• Sessions: new session creation, backfill, gateway callback registration
• Agent lifecycle: ReAct loop completion, max iterations reached, tool-aware fallback
• Tool execution: shell commands run, files written, web fetches initiated
• Security: approval decisions (approve/deny/approve-all), MCP server restarts
• Scheduling: schedule fires, manual triggers

warn

Warnings indicate degraded or blocked operations:

• Secret leaks: detected patterns and action taken (redact or block)
• Network policy: SSRF blocks (private IPs, internal hostnames), endpoint denials
• Shell policy: commands denied by allowlist/denylist
• Tool issues: execution errors, timeouts, unknown tools, rate limiting
• Injection: prompt injection patterns detected in tool output
• Approval: channel failures (auto-deny)

error

Errors indicate failures needing attention:

• Matrix login or sync failures
• Session database errors (load, persist, commit)
• Agent execution failures
• Gateway crashes

debug

Verbose output useful for development and troubleshooting:

• LLM request/response details (model, message count, finish reason)
• Individual tool results with content preview
• Model resolution (requested vs resolved, backend selected)
• File read operations with byte counts
• Memory store/recall operations
• HTTP response status and body size
• Shell command exit codes
• MCP JSON-RPC message traffic

Redirecting to a File

For --no-tui (logs default to stdout), redirect to capture them:

# Background with log file
RUST_LOG=info nohup chaz --config config.yaml --no-tui > chaz.log 2>&1 &

# Follow logs
tail -f chaz.log

TUI and -p / --print modes already log to a daily-rotated file in state_dir (see above) — no redirect needed. To follow live, tail that file in another terminal.

Security Audit Trail

For security auditing, warn level captures all enforcement actions. The exact pipeline depends on where the logs land for your gateway:

# Headless mode (`--no-tui`) — logs are on stdout/stderr, filter live
RUST_LOG=chaz_core::security=info,chaz_core::runtime=warn chaz --config config.yaml --no-tui 2>&1 | \
  grep -E "WARN|denied|blocked|SSRF|leak|Approval"

# TUI / CLI mode — logs are in a rolling file, tail and filter
tail -F ~/.local/state/chaz/chaz-tui.log | \
  grep -E "WARN|denied|blocked|SSRF|leak|Approval"

Key events to monitor:

• Secret detected in output — a tool returned content matching a secret pattern
• Network request blocked — SSRF or endpoint policy denial
• Shell command denied — command not in allowlist or on denylist
• Approval decision — tool approval granted or denied, with tool name