A practical logging schema for bots, plus heartbeat, health and alerting patterns that help diagnose problems after the fact.
In plain English
This guide focuses on what happens after the code is deployed: how to know it is alive, whether it is still doing useful work and how to recover when it is not.
health checkheartbeatstructured logsrecovery
Logs should answer five questions
What happened? When? Why? What external system was involved? What did the bot decide next?
Use structured logs
{
"ts": "2026-09-06T12:31:07Z",
"level": "INFO",
"event": "signal_rejected",
"event_id": "abc-123",
"symbol": "BTCUSD",
"reason": "spread_too_wide",
"spread_bps": 8.2
}JSON logs are easy to grep and later ingest into a log system. They also force you to name fields consistently.
Useful counters
- signals received
- signals rejected by reason
- orders attempted
- orders accepted/rejected
- API errors by status code
- session refreshes
- duplicate events
- process restarts
Heartbeat
A heartbeat should record the last successful loop, last market-data update, last broker API success and last strategy evaluation. A process can be running while no useful work is happening.
Practical lesson: “no trades today” is not automatically a bug. Logs should let you prove whether the bot had no valid signals, rejected them for a defined reason, or stopped receiving data.
Before you rely on this in production
- Heartbeat/health data has a freshness threshold.
- Alerts are actionable rather than noisy.
- Logs include correlation/event IDs.
- Recovery behavior is documented and tested.