e11994f320
- USAGE.md: alert output format, background seeding, per-backend errors, concurrent fetches - CHEATSHEET.md: updated alert section - DEBUG.md: added profiling section (cProfile + tracemalloc) - ROADMAP.md: added v1.2.1 milestone Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
153 lines
3.5 KiB
Markdown
153 lines
3.5 KiB
Markdown
# Debugging
|
|
|
|
## Verbose Mode
|
|
|
|
```bash
|
|
derp --verbose # Bare metal
|
|
make up # Compose (--verbose in compose file)
|
|
podman run ... derp --verbose # Manual container
|
|
```
|
|
|
|
Shows all IRC traffic:
|
|
|
|
```
|
|
>>> NICK derp
|
|
>>> USER derp 0 * :derp IRC bot
|
|
<<< :server 001 derp :Welcome
|
|
>>> JOIN #test
|
|
```
|
|
|
|
## Log Levels
|
|
|
|
Set in `config/derp.toml`:
|
|
|
|
```toml
|
|
[logging]
|
|
level = "debug" # debug, info, warning, error
|
|
```
|
|
|
|
Or override with `--verbose` flag (forces debug).
|
|
|
|
## Container Logs
|
|
|
|
```bash
|
|
make logs # podman-compose
|
|
podman logs -f derp # direct
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
### Connection refused
|
|
|
|
```
|
|
ERROR derp.irc connection lost: [Errno 111] Connection refused
|
|
```
|
|
|
|
- Check `host` and `port` in config
|
|
- Verify TLS setting matches port (6697 = TLS, 6667 = plain)
|
|
- Test connectivity: `nc -zv <host> <port>`
|
|
- In container: ensure DNS resolution works (check `/etc/resolv.conf`)
|
|
|
|
### Nickname in use
|
|
|
|
The bot appends `_` to the nick and retries automatically:
|
|
|
|
```
|
|
<<< :server 433 * derp :Nickname is already in use
|
|
>>> NICK derp_
|
|
```
|
|
|
|
### TLS certificate errors
|
|
|
|
For self-signed certificates, set `tls_verify = false` in config:
|
|
|
|
```toml
|
|
[server]
|
|
tls_verify = false
|
|
```
|
|
|
|
### Plugin load failures
|
|
|
|
```
|
|
ERROR derp.plugin failed to load plugin: plugins/broken.py
|
|
```
|
|
|
|
- Check plugin for syntax errors: `python -c "import py_compile; py_compile.compile('plugins/broken.py')"`
|
|
- Ensure handlers are `async def`
|
|
- Check imports (`from derp.plugin import command, event`)
|
|
- In container with mounted plugins: verify mount path and permissions
|
|
|
|
### No response to commands
|
|
|
|
- Verify `prefix` in config matches what you type
|
|
- Check that the plugin is loaded: `!plugins`
|
|
- Ensure the bot has joined the channel (check logs for `JOIN`)
|
|
- Try `!ping` first to confirm basic connectivity
|
|
|
|
### Hot-reload issues
|
|
|
|
- `!reload <plugin>` re-reads the file from disk
|
|
- In container: plugins are mounted read-only, edit on host then `!reload`
|
|
- Core plugin cannot be unloaded (but can be reloaded)
|
|
- Check logs for `loaded plugin` / `unloaded plugin` messages
|
|
|
|
### DNS plugin timeouts
|
|
|
|
- The DNS plugin uses raw UDP to the system resolver
|
|
- In container: resolver is typically `127.0.0.11` (Podman DNS)
|
|
- Fallback: `8.8.8.8` if no resolver found in `/etc/resolv.conf`
|
|
|
|
## Profiling
|
|
|
|
### CPU (cProfile)
|
|
|
|
```bash
|
|
derp --cprofile # Dump to derp.prof on shutdown
|
|
derp --cprofile /app/data/derp.prof # Custom path
|
|
```
|
|
|
|
Analyze with:
|
|
|
|
```python
|
|
import pstats
|
|
p = pstats.Stats("data/derp.prof")
|
|
p.sort_stats("tottime").print_stats(30)
|
|
p.sort_stats("cumulative").print_stats("plugins/", 20)
|
|
```
|
|
|
|
### Memory (tracemalloc)
|
|
|
|
```bash
|
|
derp --tracemalloc # 10 frames (default)
|
|
derp --tracemalloc 25 # 25 frames deep
|
|
```
|
|
|
|
Writes top 25 allocations with full tracebacks to `data/derp.malloc`
|
|
on clean shutdown. Both flags can be combined:
|
|
|
|
```bash
|
|
derp --verbose --cprofile /app/data/derp.prof --tracemalloc
|
|
```
|
|
|
|
Requires clean SIGTERM shutdown (not SIGKILL) to flush data.
|
|
Use `podman stop -t 30 derp` to allow graceful shutdown.
|
|
|
|
## Testing IRC Connection
|
|
|
|
```bash
|
|
# Test raw IRC (without the bot)
|
|
openssl s_client -connect irc.libera.chat:6697
|
|
# Then type: NICK testbot / USER testbot 0 * :test
|
|
```
|
|
|
|
## Inspecting State
|
|
|
|
From IRC, use these commands:
|
|
|
|
```
|
|
!plugins # List loaded plugins + handler counts
|
|
!help <plugin> # Show plugin description + commands
|
|
!uptime # Bot uptime
|
|
!version # Running version
|
|
```
|