Alexis Bruneteau 7b9d6d0407 docs: Add comprehensive logging guide for backend debugging

Guide covers:
- What's logged at each stage
- Log levels and emoji indicators
- Common log patterns
- Docker log commands
- Debugging with logs
- Performance monitoring
- Troubleshooting checklist
- Real-time monitoring
- Example analysis

Helps users understand:
- Backend startup sequence
- Blockchain operations
- Error detection
- System health
- Performance tracking

2025-11-07 03:07:05 +01:00

9.9 KiB

Raw Permalink Blame History

Backend Logging Guide

Overview

The E-Voting backend now includes comprehensive structured logging to help debug issues and understand the system's behavior.

What's Logged

Startup Sequence

🚀 Starting E-Voting Backend
📦 Initializing database...
✓ Database initialized successfully
⛓️  Initializing blockchain...
  ✓ Recorded election 1 (Election Présidentielle 2025)
    Block #0, Hash: 7f3e9c2b1d4f..., Candidates: 4
✓ Blockchain initialization completed
✓ Backend initialization complete, starting FastAPI app

Blockchain Operations

Blockchain Initialization Started
Found 1 elections in database
Blockchain currently has 0 elections
  ✓ Recorded election 1 (Election Présidentielle 2025)
    Block #0, Hash: 7f3e9c2b..., Candidates: 4
Recording summary: 1 new, 0 skipped
Verifying blockchain integrity (1 blocks)...
✓ Blockchain integrity verified successfully
Blockchain Initialization Complete
  Total blocks: 1
  Chain valid: true

Election Creation

✓ Election 1 recorded to blockchain (Block #0, Hash: 7f3e9c2b...)

Errors and Warnings

❌ Failed to record election 1 to blockchain: [error details]
⚠️  Blockchain initialization failed (non-fatal): [error details]
🔥 Critical failure: [error details]

Logging Levels

Level	Emoji	Use Case
DEBUG	🔍	Detailed diagnostic information, variable states
INFO	ℹ️	General informational messages, success confirmations
WARNING	⚠️	Warning messages, potential issues (non-fatal)
ERROR	❌	Error messages, failures that need attention
CRITICAL	🔥	Critical failures that may prevent operation

Reading Log Output

Example Log Entry

ℹ️  2025-11-07 02:03:15 - backend.init_blockchain - INFO - ✓ Recorded election 1 (Election Présidentielle 2025)
                       Block #0, Hash: 7f3e9c2b1d4f..., Candidates: 4

Parts:

ℹ️ - Log level emoji
2025-11-07 02:03:15 - Timestamp
backend.init_blockchain - Module that logged it
INFO - Log level
Rest is the message

Common Log Patterns

Successful Blockchain Initialization

Blockchain Initialization Started
Found 1 elections in database
Blockchain currently has 0 elections
  ✓ Recorded election 1 (Election Présidentielle 2025)
    Block #0, Hash: 7f3e9c2b..., Candidates: 4
Recording summary: 1 new, 0 skipped
✓ Blockchain integrity verified successfully
Blockchain Initialization Complete

✓ Status: Backend is working correctly

Election Already on Blockchain

  ⊘ Election 1 (Election Présidentielle 2025) already on blockchain
Recording summary: 0 new, 1 skipped

✓ Status: Restart is safe, election already recorded

Database Connection Error

❌ Database initialization failed: [error details]

✗ Status: Database isn't accessible, check connection settings

Blockchain Corruption Detected

✗ Blockchain integrity check FAILED - possible corruption!

✗ Status: Blockchain data is corrupted, investigate immediately

Docker Logs

View All Logs

docker compose -f docker-compose.multinode.yml logs -f

View Backend Logs Only

docker compose -f docker-compose.multinode.yml logs -f backend-node-1
docker compose -f docker-compose.multinode.yml logs -f backend-node-2
docker compose -f docker-compose.multinode.yml logs -f backend-node-3

View Database Logs

docker compose -f docker-compose.multinode.yml logs -f mariadb

View Frontend Logs

docker compose -f docker-compose.multinode.yml logs -f frontend

View Nginx Load Balancer Logs

docker compose -f docker-compose.multinode.yml logs -f nginx

Debugging with Logs

Problem: 502 Bad Gateway

Check logs:

docker compose logs backend-node-1 2>&1 | tail -100

Look for:

❌ Database initialization failed - Database won't connect
⚠️ Blockchain initialization failed - Blockchain error (non-fatal)
Exception with full traceback - What specifically failed
Module import errors - Missing or broken imports

Problem: No Elections on Blockchain

Check logs:

docker compose logs backend-node-1 | grep -i blockchain

Look for:

Found X elections in database - Are there elections?
✓ Recorded election - Did recording succeed?
Recording summary - How many were recorded vs skipped?
✓ Blockchain integrity verified - Is blockchain valid?

Problem: Slow Startup

Check logs:

docker compose logs backend-node-1 | grep -i "started\|initialized\|complete"

Look for:

How long between "Starting" and "initialized successfully"
Any pauses or long operations
Database queries taking time

Logging Configuration

File: backend/logging_config.py

Controls:

Log levels per module
Output format (colors, emojis, timestamps)
Which third-party loggers to suppress (SQLAlchemy, Uvicorn, etc.)

Modify Log Levels

To change log levels at runtime:

# In backend code
import logging

# Get a logger
logger = logging.getLogger('backend.blockchain_elections')

# Change level
logger.setLevel(logging.DEBUG)  # More verbose
logger.setLevel(logging.WARNING)  # Less verbose

Or in logging_config.py:

def setup_logging(level=logging.INFO):
    # Change specific module levels
    logging.getLogger('backend.blockchain_elections').setLevel(logging.DEBUG)
    logging.getLogger('backend.services').setLevel(logging.WARNING)

Modules and Their Log Output

`backend.main`

Backend startup sequence
Initialization status
Fatal errors

`backend.init_blockchain`

Blockchain initialization
Election recording
Integrity verification
Startup profiling

`backend.services`

Election creation
Voter operations
Vote recording
Database operations

`backend.routes`

API endpoint calls
Request/response info
Validation errors

`backend.database`

Database connection
Migration status
Connection pooling info

Performance Monitoring with Logs

Track Blockchain Initialization Time

docker compose logs backend-node-1 | grep "Blockchain Initialization"

Output shows:

When it started
When it completed
How many elections processed

Calculate total time: start_time to complete_time

Track Election Recording Time

docker compose logs backend-node-1 | grep "Recorded election"

Each line shows:

Election ID and name
Block number assigned
Hash of the block
Candidate count

Track Request Processing

docker compose logs backend-node-1 | grep "API\|request"

Shows which endpoints were called and when

Exporting Logs

Save to File

docker compose logs backend-node-1 > backend_logs.txt

Search Logs for Pattern

docker compose logs | grep "❌\|✗"  # Errors and failures
docker compose logs | grep "✓"      # Successes
docker compose logs | grep "⚠️"      # Warnings

Get Last N Lines

docker compose logs backend-node-1 --tail 50

Get Logs Since Time

docker compose logs --since 2025-11-07T02:00:00

Troubleshooting Checklist

When something goes wrong:

Check backend logs for errors: docker compose logs backend-node-1
Look for stack traces with Exception or Error
Check database logs: docker compose logs mariadb
Check if database initialized successfully
Check if blockchain recorded elections
Verify blockchain integrity status
Check Nginx load balancer logs: docker compose logs nginx
Verify all containers are healthy: docker compose ps

Example Log Analysis

Scenario: Getting 502 errors but frontend loads

Log search:

docker compose logs backend-node-1 | head -100

Expected healthy logs:

🚀 Starting E-Voting Backend
📦 Initializing database...
✓ Database initialized successfully
⛓️  Initializing blockchain...
✓ Blockchain initialization completed
✓ Backend initialization complete, starting FastAPI app

Red flags:

❌ Database initialization failed     <- Backend can't connect to DB
⚠️  Blockchain initialization failed  <- Blockchain issue (non-fatal)
Exception in...                        <- Python error
Traceback...                           <- Stack trace

Next steps:

If database failed: check MariaDB is running
If blockchain failed: check elections table has data
If exception: read the full traceback for details

Real-Time Monitoring

Watch Logs as Backend Starts

docker compose logs -f backend-node-1

Press Ctrl+C to stop. Useful for:

Watching initialization progress
Seeing exactly when things complete
Catching errors as they happen

Monitor Multiple Services

docker compose logs -f

Shows all logs from all services in real-time

Questions the Logs Answer

Question	Where to Look
Why can't the backend connect to DB?	`backend.main` logs for `Database initialization failed`
Are elections being recorded to blockchain?	`backend.init_blockchain` logs for `Recorded election`
Is the blockchain valid?	`backend.init_blockchain` logs for `Blockchain integrity verified`
How long does startup take?	Timestamps between `Starting` and `complete`
What happened to my election creation?	`backend.services` logs for `Election recorded to blockchain`
Why are API requests failing?	`backend.routes` logs and `nginx` logs
Is the database healthy?	`mariadb` logs and connection messages in `backend.main`

Summary

The enhanced logging provides:

✓ Clear visibility into system state
✓ Colored output for easy scanning
✓ Emoji prefixes for quick identification
✓ Timestamp and module information
✓ Full exception details for debugging
✓ Separate concerns for different modules

Use the logs to:

Understand what's happening
Identify where failures occur
Debug issues quickly
Monitor system health
Track performance

9.9 KiB Raw Permalink Blame History Unescape Escape

Backend Logging Guide

Overview

What's Logged

Startup Sequence

Blockchain Operations

Election Creation

Errors and Warnings

Logging Levels

Reading Log Output

Example Log Entry

Common Log Patterns

Successful Blockchain Initialization

Election Already on Blockchain

Database Connection Error

Blockchain Corruption Detected

Docker Logs

View All Logs

View Backend Logs Only

View Database Logs

View Frontend Logs

View Nginx Load Balancer Logs

Debugging with Logs

Problem: 502 Bad Gateway

Problem: No Elections on Blockchain

Problem: Slow Startup

Logging Configuration

Modify Log Levels

Modules and Their Log Output

backend.main

backend.init_blockchain

backend.services

backend.routes

backend.database

Performance Monitoring with Logs

Track Blockchain Initialization Time

Track Election Recording Time

Track Request Processing

Exporting Logs

Save to File

Search Logs for Pattern

Get Last N Lines

Get Logs Since Time

Troubleshooting Checklist

Example Log Analysis

Real-Time Monitoring

Watch Logs as Backend Starts

Monitor Multiple Services

Questions the Logs Answer

Summary

9.9 KiB

Raw Permalink Blame History

`backend.main`

`backend.init_blockchain`

`backend.services`

`backend.routes`

`backend.database`