derp/docs/DEBUG.md

Debugging

Verbose Mode

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:

[logging]
level = "debug"    # debug, info, warning, error

Or override with --verbose flag (forces debug).

Container Logs

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:

[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)

derp --cprofile                     # Dump to derp.prof on shutdown
derp --cprofile /app/data/derp.prof # Custom path

Analyze with:

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)

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:

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

# 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