Skip to content

Debugging And Diagnostics

This document covers supported diagnostic paths for the current runtime.

Increase Log Detail

For the Docker image:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --group-add "$(stat -c %g /var/run/docker.sock)" \
  -v /path/to/pytmbot.yaml:/opt/app/pytmbot.yaml:ro \
  orenlab/pytmbot:stable \
  --mode prod --log-level DEBUG

For local execution:

uv run python pytmbot/main.py --mode dev --log-level DEBUG

Notes:

  • DEBUG keeps full stack traces.
  • INFO and above keep logs concise.
  • --log-format human is easier for interactive debugging.

Container Logs

docker logs pytmbot
docker logs -f pytmbot

Health Diagnostics

Application-level health status (reads the snapshot written by a running bot; exit code 0 healthy, 1 unhealthy or stale, 2 no snapshot yet):

uv run python pytmbot/main.py --health_check

Health of a running container (a one-off docker run ... --health_check has no running bot and reports "no health data"):

docker inspect --format '{{json .State.Health}}' pytmbot
docker exec pytmbot ./entrypoint.sh --health_check

Docker access validation:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --group-add "$(stat -c %g /var/run/docker.sock)" \
  orenlab/pytmbot:stable \
  --check-docker

Common Failure Areas

Check these first:

  • wrong bot token in pytmbot.yaml
  • missing allowlist entries in access_control
  • Docker socket not mounted or inaccessible
  • webhook host or port mismatch
  • missing influxdb config when monitor plugin is enabled
  • missing plugins_config.outline fields when outline is enabled

Useful References