Skip to main content

​
Diagnostics Flags

Diagnostics flags let you enable targeted debug logs without turning on verbose logging everywhere. Flags are opt-in and have no effect unless a subsystem checks them.

​
How it works

  • Flags are strings (case-insensitive).
  • You can enable flags in config or via an env override.
  • Wildcards are supported:
    • telegram.* matches telegram.http
    • * enables all flags

​
Enable via config

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}
Multiple flags: 
{
  "diagnostics": {
    "flags": ["telegram.http", "gateway.*"]
  }
}
Restart the gateway after changing flags.

​
Env override (one-off)

CLAWDIA_DIAGNOSTICS=telegram.http,telegram.payload
Disable all flags: 
CLAWDIA_DIAGNOSTICS=0

​
Where logs go

Flags emit logs into the standard diagnostics log file. By default: 
/tmp/nelsonmuntz-c/clawdia-YYYY-MM-DD.log
If you set logging.file, use that path instead. Logs are JSONL (one JSON object per line). Redaction still applies based on logging.redactSensitive.

​
Extract logs

Pick the latest log file: 
ls -t /tmp/nelsonmuntz-c/clawdia-*.log | head -n 1
Filter for Telegram HTTP diagnostics: 
rg "telegram http error" /tmp/nelsonmuntz-c/clawdia-*.log
Or tail while reproducing: 
tail -f /tmp/nelsonmuntz-c/clawdia-$(date +%F).log | rg "telegram http error"
For remote gateways, you can also use clawdia logs --follow (see /cli/logs).

​
Notes

  • If logging.level is set higher than warn, these logs may be suppressed. Default info is fine.
  • Flags are safe to leave enabled; they only affect log volume for the specific subsystem.
  • Use /logging to change log destinations, levels, and redaction.