Logging 101: Hoe je een 'Audit Trail' maakt van elke beslissing

Alex de Vries

Quantitatief Analist & Algo-Trading Expert

Je bot draait, de markt beweegt, en opeens gebeurt er iets raars.

Je weet niet precies wat er misging, waarom die trade werd geplaatst of welke data er op dat moment binnenkwam. Zonder een goede log heb je geen poot om op te staan. Een audit trail is je zwarte doos voor algoritmische trading.

Het is het verhaal achter elke beslissing, elke API-call en elke fout. In dit stuk bouwen we die trail op, stap voor stap, zodat je nooit meer in het duister tast.

Wat je nodig hebt voordat je start

Je hebt een werkende Python-omgeving nodig. Gebruik Python 3.9 of nieuwer, want de logging-module is daar stabieler.

Zorg dat je een virtuele omgeving draait, bijvoorbeeld met venv of conda. Installeer de volgende packages: ccxt (voor broker-API’s), pandas (voor data), structlog (voor JSON-logs) en python-json-logger (voor leesbare output). Reken op een paar minuten installatietijd.

Je broker- of exchange-account moet API-toegang hebben. Bijvoorbeeld bij Interactive Brokers (IBKR), Binance, Bybit of Kraken.

Zorg voor een testaccount met €100-€500 speelgeld. Gebruik nooit een productieaccount zonder gedegen logging. Logfiles kunnen snel groeien; zorg voor minimaal 2 GB vrije schijfruimte.

Een SSD helpt, maar is geen harde eis. Je backtesting-omgeving moet compatibel zijn met je live-bot.

Gebruik dezelfde logging-configuratie, zodat je logs tussen backtest en live kunt vergelijken.

Denk aan een mapstructuur als logs/ met submappen per bot, per datum en per broker. Zet een eenvoudig Git-repo op voor versiebeheer van je bot-code en je logging-config. Zo los je het op als je bot wel draait maar geen orders plaatst.

Stap 1: Kies je logformaat en -niveau

1. Bepaal het formaat: kies voor JSON-logging. JSON is machineleesbaar en makkelijk te doorzoeken. Gebruik structlog voor een gestructureerde output.
2. Kies het logniveau: DEBUG voor development, INFO voor normale operaties, WARNING voor waarschuwingen, ERROR voor fouten, CRITICAL voor crashes. Zet live op INFO, en schakel DEBUG in tijdens het debuggen.
3. Stel de tijdzone in: gebruik UTC voor consistentie. Dat voorkomt problemen bij internationale brokers en tijdzones.
4. Maak een logging-configuratiebestand (logging.conf) of zet het rechtstreeks in Python. Voorbeeld: logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s').
5. Test je niveau: schrijf een testlog op elk niveau en controleer of het verschil zichtbaar is.

Veelgemaakte fouten: vergeten niveaus instellen, lokale tijd gebruiken zonder timezone, of teveel ruis in de log door te weinig filters. Tijdsindicatie: 10-15 minuten.

“Als je niet weet wat er op 13:42:07 UTC gebeurde, heb je geen controle over je bot.”

Stap 2: Leg elke beslissing vast met context

1. Log elke trigger: wanneer een signaal ontstaat (bijv. SMA-crossover, RSI-grens, orderbook-delta). Sla de exacte timestamp, symbool en broker op.
2. Log de data die de trigger veroorzaakte: prijs, volume, spread, orderboekniveau’s. Bijvoorbeeld: “ETH/USDT, bid 2.100, ask 2.102, spread 0,095%”.
3. Log het beslissingsproces: welke regel is afgevallen, welke is doorgegaan? Sla variabelen op, zoals rsi=68, sma_short=2.050, sma_long=2.040.
4. Log de orderdetails: ordertype (limit/market), kant (buy/sell), grootte (bijv. 0,5 ETH), prijs (limietprijs), en TTL (time-to-live).
5. Log het resultaat: order-ID, fill-prijs, fee (in € of quote currency), en status (filled, partial, rejected, canceled).
6. Log afwijkingen: als een order niet wordt uitgevoerd, noteer waarom (te lage limiet, onvoldoende balance, API-fout).

Gebruik een context-dict per event: {"symbol": "ETH/USDT", "exchange": "binance", "strategy": "sma_crossover", "timestamp": "2024-01-15T13:42:07Z"}. Dat maakt later filteren en zoeken veel makkelijker.

Tijdsindicatie: 20-25 minuten voor een eerste implementatie. Veelgemaakte fouten: alleen de order loggen zonder datacontext, of timestamps zonder timezone.

Doe het meteen goed, dan bespaar je jezelf later uren speurwerk.

Stap 3: Schrijf je logs naar bestanden en stdout

1. Maak een map logs/ met submappen per bot en per datum, bijvoorbeeld logs/bot_sma/binance/2024-01-15/.
2. Gebruik RotatingFileHandler: draai elke 10 MB en bewaar maximaal 5 bestanden per bot. Zo voorkomt je dat je schijf volloopt.
3. Log naar stdout voor container-omgevingen (Docker/Kubernetes). Zo kun je stdout vangen met monitoring-tools.
4. Splits logs: aparte bestanden voor trade-events, API-calls, errors en performance. Bijvoorbeeld: trades.jsonl, api.jsonl, errors.jsonl.
5. Voeg een unieke run-ID toe per sessie: een UUID of timestamp. Handig om logs per run te groeperen.

Stel in: logging.handlers.RotatingFileHandler('logs/trades.jsonl', maxBytes=10_000_000, backupCount=5). Gebruik JSON-formatter voor structlog. Vergeet ook je database backups niet. Tijdsindicatie: 15-20 minuten.

Veelgemaakte fouten: logs naar één groot bestand schrijven zonder rotatie, of vergeten run-ID toe te voegen. Zonder run-ID wordt zoeken een chaos.

Stap 4: Log API-interacties en fouten

1. Pak de broker-API aan met ccxt. Log elke request: endpoint, methode (GET/POST), parameters, en timestamp.
2. Log responses: statuscode, payload-grootte, en foutmeldingen. Beperk de grootte van payloads in de log (bijv. max 200 regels orderbook) om performance te behouden.
3. Log ratelimits: noteer remaining requests en reset-tijd. Bij Binance bijvoorbeeld: remaining=850, reset_in=60s.
4. Log errors met traceback: gebruik logging.exception("Fout bij order plaatsen") voor volledige stacktrace.
5. Log herstelacties: als een request faalt, log welke retry wordt geprobeerd en wat het resultaat is.

Specifieke getallen: houd een maximum van 5 retries per request, met een backoff van 1s, 2s, 4s, 8s, 16s. Log elke stap. Tijdsindicatie: 20-30 minuten.

Veelgemaakte fouten: volledige payloads dumpen zonder filtering (privacy- en performance-risico), of geen retry-logging, waardoor je niet weet of een herstelpoging werkte.

Stap 5: Bouw een audit trail voor risicomanagement

1. Log risicogrenzen: maximale exposure per symbool (bijv. €2.000), max drawdown (bijv. 5%), en stoploss-niveaus.
2. Log portfolio-state: cash, margin, exposure, en onrealized PnL. Check dit voor elke trade.
3. Log beslissingen rond risico: als een trade wordt geblokkeerd vanwege exposure, log de reden en de huidige exposure.
4. Log prestaties: winst/verlies per trade, cumulative PnL, en slippage. Gebruik aparte logregels voor deze metrics.
5. Log compliance: bijvoorbeeld voor IBKR, log of de trade voldoet aan de Pattern Day Trader-regel (als van toepassing) en aan je eigen regels.

Gebruik een risico-log per run: risk_<run-ID>.jsonl. Tijdsindicatie: 15-20 minuten. Veelgemaakte fouten: risico-regels niet loggen, of alleen het resultaat loggen zonder de afweging ertussen.

Een audit trail moet het denkproces tonen, niet alleen de uitkomst.

Stap 6: Analyseer en verifieer je logs

1. Open je logs in een tool: jq voor JSONL, of Pandas voor analyse. Voorbeeld: jq '. | select(.event=="order")' trades.jsonl.
2. Check consistentie: vergelijk timestamps tussen trigger, order en fill. Zoek naar gaten langer dan 500 ms.
3. Check volledigheid: ontbreken er API-calls of foutmeldingen? Zijn alle risico-events aanwezig?
4. Test reproduceerbaarheid: draai een backtest met dezelfde logs en controleer of de beslissingen identiek zijn.
5. Archiveer logs: bewaar 30 dagen live en 90 dagen backtest. Gebruik compressie (gzip) om ruimte te besparen.

Veelgemaakte fouten: logs niet controleren op volledigheid, of geen archiveringsbeleid hebben. Een goede audit trail is pas nuttig als je hem kunt doorzoeken en bewaren.

Verificatie-checklist

• JSON-logging ingesteld met structlog en UTC-tijdzone.
• Logniveau’s geconfigureerd (DEBUG/INFO/WARNING/ERROR/CRITICAL).
• Elke trigger, data-context en order vastgelegd met run-ID.
• Rotatie ingesteld: 10 MB per bestand, max 5 backups.
• API-requests en responses gelogd, inclusief ratelimits en retries.
• Risicogrenzen en portfolio-state gelogd vóór elke trade.
• Fouten gelogd met traceback en herstelacties.
• Logs geanalyseerd met jq of Pandas en consistent bevonden.
• Archiveerbeleid actief: 30 dagen live, 90 dagen backtest.

Als je deze checklist aftikt, heb je een stevige audit trail die je helpt fouten in je trading bots op te sporen, risico’s te beheren en je bot betrouwbaarder te maken. En dat zonder uren zoeken naar de oorzaak van een mysterieuze order.