Monitoring Setup¶

The project includes a Docker Compose stack for centralized log monitoring using Grafana, Loki, and Alloy.

Architecture¶

flowchart LR
    Bot["Grid Trading Bot"] -->|writes logs| Logs["logs/*.log"]
    Logs -->|tails files| Alloy["Alloy v1.13.2"]
    Alloy -->|pushes logs| Loki["Loki 3.6.7"]
    Loki -->|queries| Grafana["Grafana 12.4.0"]

Prerequisites¶

• Docker and Docker Compose installed
• A .env file with Grafana credentials (see Environment Variables)

Start the Stack¶

docker-compose up -d

This starts three services:

Run the Bot with Docker Compose¶

The bot itself is available as an optional Compose service behind the bot profile, so docker-compose up -d keeps starting the monitoring stack only.

# Build the bot image and start everything (monitoring + bot)
docker-compose --profile bot up -d --build

The service is defined for 24/7 operation on a VPS:

• restart: unless-stopped — auto-restart on crash and on reboot
• ./data volume — the SQLite state survives restarts, and the recovery service reconciles it with the exchange on startup
• ./logs volume — the bot writes its logs where Alloy tails them, so they show up in Grafana automatically
• stdin_open: true — keeps the live-mode command listener idle instead of spinning on EOF in a detached container

By default the bot runs with config/config.json, which is a backtest configuration: it runs once, exits, and the restart policy would run it again. For a long-running deployment, point the service at a live configuration via the BOT_CONFIG variable in your .env file:

# .env
BOT_CONFIG=config/config.live.json
EXCHANGE_API_KEY=your_api_key
EXCHANGE_SECRET_KEY=your_secret_key

See config/config.live.example.json for a live configuration template.

To follow the bot output, stop it, or deploy a new version:

docker-compose logs -f bot

# Graceful stop (sends SIGINT so the bot shuts down cleanly)
docker-compose --profile bot stop bot

# Rebuild and restart after a git pull
docker-compose --profile bot up -d --build bot

Access Grafana¶

1. Navigate to http://localhost:3000
2. Log in with the credentials from your .env file:
   • Username: value of GRAFANA_ADMIN_USER (default: admin)
   • Password: value of GRAFANA_ADMIN_PASSWORD

Loki is pre-configured as the default datasource.

Log Pipeline¶

How Alloy Processes Logs¶

Alloy tails all .log files from the logs/ directory and extracts structured labels from the log filenames.

Labels extracted from filename:

A derived trading_pair label is created by combining base_currency/quote_currency (e.g., SOL/USDT).

Log Format Parsing¶

Alloy parses each log line to extract:

• Timestamp — Used for time-series indexing in Loki
• Service — The component that emitted the log
• Level — Log severity (DEBUG, INFO, WARNING, ERROR)
• Message — The log content

Alert Rules¶

Two alert rules are pre-configured in Loki:

Alert rules are defined in monitoring/configs/loki/rules.yaml.

Configuration Files¶

Stop the Stack¶

docker-compose down

To also remove stored data:

docker-compose down -v