docs: Add logging implementation summary
This commit is contained in:
Alexis Bruneteau
parent
7b9d6d0407
commit
99ec83dd0c
415
e-voting-system/LOGGING_IMPLEMENTATION_SUMMARY.md
Normal file
415
e-voting-system/LOGGING_IMPLEMENTATION_SUMMARY.md
Normal file
@ -0,0 +1,415 @@
|
|||||||
|
# Backend Logging Implementation - Summary
|
||||||
|
|
||||||
|
## What Was Added
|
||||||
|
|
||||||
|
Comprehensive structured logging throughout the backend to help understand what's happening and debug issues.
|
||||||
|
|
||||||
|
### New Files
|
||||||
|
|
||||||
|
1. **`backend/logging_config.py`** (85 lines)
|
||||||
|
- Centralized logging configuration
|
||||||
|
- Colored output with emojis
|
||||||
|
- Custom formatter for better readability
|
||||||
|
- Log level management by module
|
||||||
|
|
||||||
|
### Modified Files
|
||||||
|
|
||||||
|
1. **`backend/main.py`**
|
||||||
|
- Enhanced startup logging
|
||||||
|
- Shows initialization progress
|
||||||
|
- Logs errors with full details
|
||||||
|
- Uses colored logging
|
||||||
|
|
||||||
|
2. **`backend/init_blockchain.py`**
|
||||||
|
- Detailed blockchain initialization logging
|
||||||
|
- Shows elections loaded from database
|
||||||
|
- Reports election recording progress
|
||||||
|
- Displays verification status
|
||||||
|
- Counts new vs. skipped elections
|
||||||
|
|
||||||
|
3. **`backend/services.py`**
|
||||||
|
- Logs election creation
|
||||||
|
- Shows blockchain recording status
|
||||||
|
- Reports block hash and number
|
||||||
|
- Includes error details
|
||||||
|
|
||||||
|
## What Gets Logged
|
||||||
|
|
||||||
|
### Startup Sequence
|
||||||
|
|
||||||
|
```
|
||||||
|
🚀 Starting E-Voting Backend
|
||||||
|
========================================
|
||||||
|
📦 Initializing database...
|
||||||
|
✓ Database initialized successfully
|
||||||
|
⛓️ Initializing blockchain...
|
||||||
|
✓ Recorded election 1 (Election Présidentielle 2025)
|
||||||
|
Block #0, Hash: 7f3e9c2b..., 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
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ Database initialization failed: ConnectionError: Can't connect to database
|
||||||
|
⚠️ Blockchain initialization failed (non-fatal): ValueError: Invalid election data
|
||||||
|
🔥 Critical failure: SystemError: Database corrupted
|
||||||
|
```
|
||||||
|
|
||||||
|
## Logging Features
|
||||||
|
|
||||||
|
### Emoji Prefixes
|
||||||
|
- 🔍 DEBUG - Detailed diagnostic information
|
||||||
|
- ℹ️ INFO - General informational messages
|
||||||
|
- ⚠️ WARNING - Warning messages (non-fatal)
|
||||||
|
- ❌ ERROR - Error messages
|
||||||
|
- 🔥 CRITICAL - Critical failures
|
||||||
|
|
||||||
|
### Color Coding
|
||||||
|
- Cyan for DEBUG
|
||||||
|
- Green for INFO
|
||||||
|
- Yellow for WARNING
|
||||||
|
- Red for ERROR
|
||||||
|
- Magenta for CRITICAL
|
||||||
|
|
||||||
|
### Information Included
|
||||||
|
- Timestamp (YYYY-MM-DD HH:MM:SS)
|
||||||
|
- Logger module name
|
||||||
|
- Log level
|
||||||
|
- Formatted message
|
||||||
|
- Full exception stack trace on errors
|
||||||
|
|
||||||
|
## How to Use
|
||||||
|
|
||||||
|
### View Backend Logs
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# View all backend logs
|
||||||
|
docker compose -f docker-compose.multinode.yml logs -f backend-node-1
|
||||||
|
|
||||||
|
# Search for blockchain operations
|
||||||
|
docker compose logs backend-node-1 | grep -i blockchain
|
||||||
|
|
||||||
|
# Search for errors
|
||||||
|
docker compose logs backend-node-1 | grep "❌\|✗"
|
||||||
|
|
||||||
|
# Get last 50 lines
|
||||||
|
docker compose logs backend-node-1 --tail 50
|
||||||
|
```
|
||||||
|
|
||||||
|
### Interpret Logs
|
||||||
|
|
||||||
|
**Healthy startup:**
|
||||||
|
```
|
||||||
|
✓ Database initialized successfully
|
||||||
|
✓ Blockchain initialization completed
|
||||||
|
✓ Backend initialization complete
|
||||||
|
```
|
||||||
|
|
||||||
|
**Database issue:**
|
||||||
|
```
|
||||||
|
❌ Database initialization failed: Can't connect to 'localhost:3306'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Blockchain issue:**
|
||||||
|
```
|
||||||
|
Found 1 elections in database
|
||||||
|
Blockchain currently has 0 elections
|
||||||
|
✓ Recorded election 1 to blockchain
|
||||||
|
✓ Blockchain integrity verified successfully
|
||||||
|
```
|
||||||
|
|
||||||
|
**Already initialized:**
|
||||||
|
```
|
||||||
|
⊘ Election 1 already on blockchain
|
||||||
|
Recording summary: 0 new, 1 skipped
|
||||||
|
```
|
||||||
|
|
||||||
|
## Benefits
|
||||||
|
|
||||||
|
### For Debugging
|
||||||
|
- ✓ See exactly what's happening at startup
|
||||||
|
- ✓ Identify exactly where failures occur
|
||||||
|
- ✓ Full stack traces for exceptions
|
||||||
|
- ✓ Database connection status
|
||||||
|
- ✓ Blockchain recording progress
|
||||||
|
|
||||||
|
### For Monitoring
|
||||||
|
- ✓ Track initialization time
|
||||||
|
- ✓ Monitor election recording
|
||||||
|
- ✓ Verify blockchain integrity
|
||||||
|
- ✓ Watch performance metrics
|
||||||
|
- ✓ Detect unusual patterns
|
||||||
|
|
||||||
|
### For Operations
|
||||||
|
- ✓ Understand system health
|
||||||
|
- ✓ Troubleshoot issues faster
|
||||||
|
- ✓ Verify configuration
|
||||||
|
- ✓ Track error rates
|
||||||
|
- ✓ Historical logs for analysis
|
||||||
|
|
||||||
|
## Log Levels and What They Mean
|
||||||
|
|
||||||
|
### DEBUG (🔍)
|
||||||
|
```
|
||||||
|
🔍 Recording election 1 (Election Présidentielle 2025) to blockchain
|
||||||
|
🔍 Found 4 candidates for election 1
|
||||||
|
```
|
||||||
|
**When to use:** Detailed info for developers. Not in production logs by default.
|
||||||
|
|
||||||
|
### INFO (ℹ️)
|
||||||
|
```
|
||||||
|
ℹ️ Found 1 elections in database
|
||||||
|
ℹ️ ✓ Recorded election 1 to blockchain
|
||||||
|
ℹ️ ✓ Blockchain integrity verified successfully
|
||||||
|
```
|
||||||
|
**When to use:** Important events and successes. Normal operation.
|
||||||
|
|
||||||
|
### WARNING (⚠️)
|
||||||
|
```
|
||||||
|
⚠️ Blockchain initialization failed (non-fatal): Database busy
|
||||||
|
```
|
||||||
|
**When to use:** Something unexpected but not critical. System continues.
|
||||||
|
|
||||||
|
### ERROR (❌)
|
||||||
|
```
|
||||||
|
❌ Database initialization failed: ConnectionError
|
||||||
|
```
|
||||||
|
**When to use:** Something failed that needs attention. May cause issues.
|
||||||
|
|
||||||
|
### CRITICAL (🔥)
|
||||||
|
```
|
||||||
|
🔥 Failed to start FastAPI app
|
||||||
|
```
|
||||||
|
**When to use:** System cannot continue. Immediate action needed.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
**File:** `backend/logging_config.py`
|
||||||
|
|
||||||
|
### Default Levels
|
||||||
|
```python
|
||||||
|
'backend': INFO # General backend operations
|
||||||
|
'backend.blockchain_elections': DEBUG # Detailed blockchain info
|
||||||
|
'backend.init_blockchain': INFO # Initialization
|
||||||
|
'backend.services': INFO # Service operations
|
||||||
|
'backend.main': INFO # Main startup
|
||||||
|
```
|
||||||
|
|
||||||
|
### Suppress Verbose Loggers
|
||||||
|
```python
|
||||||
|
'sqlalchemy.engine': WARNING # Don't log SQL queries
|
||||||
|
'sqlalchemy.pool': WARNING # Don't log pool events
|
||||||
|
'uvicorn': INFO # Minimal Uvicorn logs
|
||||||
|
'uvicorn.access': WARNING # Don't log access requests
|
||||||
|
```
|
||||||
|
|
||||||
|
### Customize
|
||||||
|
|
||||||
|
To change logging in `logging_config.py`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def setup_logging(level=logging.INFO):
|
||||||
|
# Make blockchain more verbose
|
||||||
|
logging.getLogger('backend.blockchain_elections').setLevel(logging.DEBUG)
|
||||||
|
|
||||||
|
# Make services less verbose
|
||||||
|
logging.getLogger('backend.services').setLevel(logging.WARNING)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Docker Integration
|
||||||
|
|
||||||
|
### Multi-Node Setup
|
||||||
|
|
||||||
|
Each backend node logs independently:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Node 1
|
||||||
|
docker compose logs backend-node-1
|
||||||
|
|
||||||
|
# Node 2
|
||||||
|
docker compose logs backend-node-2
|
||||||
|
|
||||||
|
# Node 3
|
||||||
|
docker compose logs backend-node-3
|
||||||
|
|
||||||
|
# All
|
||||||
|
docker compose logs
|
||||||
|
```
|
||||||
|
|
||||||
|
### View Logs in Real-Time
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Follow logs as they appear
|
||||||
|
docker compose logs -f backend-node-1
|
||||||
|
|
||||||
|
# Stop with Ctrl+C
|
||||||
|
```
|
||||||
|
|
||||||
|
### Export Logs
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Save to file
|
||||||
|
docker compose logs backend-node-1 > backend.log
|
||||||
|
|
||||||
|
# Search exported logs
|
||||||
|
grep "Error\|blockchain" backend.log
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting Examples
|
||||||
|
|
||||||
|
### Example 1: 502 Bad Gateway
|
||||||
|
|
||||||
|
**What to check:**
|
||||||
|
```bash
|
||||||
|
docker compose logs backend-node-1 | head -50
|
||||||
|
```
|
||||||
|
|
||||||
|
**Look for:**
|
||||||
|
```
|
||||||
|
❌ Database initialization failed
|
||||||
|
└─ ConnectionError: Can't connect to 'mariadb:3306'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fix:** Start MariaDB: `docker compose up -d mariadb`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Example 2: No Elections on Blockchain
|
||||||
|
|
||||||
|
**What to check:**
|
||||||
|
```bash
|
||||||
|
docker compose logs backend-node-1 | grep blockchain
|
||||||
|
```
|
||||||
|
|
||||||
|
**Look for:**
|
||||||
|
```
|
||||||
|
Found 0 elections in database
|
||||||
|
└─ Nothing to record!
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fix:** Database initialization scripts haven't run. Wait longer or restart DB.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Example 3: Blockchain Corruption
|
||||||
|
|
||||||
|
**What to check:**
|
||||||
|
```bash
|
||||||
|
docker compose logs backend-node-1 | grep "integrity"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Look for:**
|
||||||
|
```
|
||||||
|
✗ Blockchain integrity check FAILED - possible corruption!
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fix:** Restart backend: `docker compose restart backend-node-1`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Example 4: Slow Startup
|
||||||
|
|
||||||
|
**What to check:**
|
||||||
|
```bash
|
||||||
|
# Watch logs during startup
|
||||||
|
docker compose logs -f backend-node-1 | grep -i "starting\|complete"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Look for:**
|
||||||
|
- Time between "Starting" and "complete"
|
||||||
|
- Any pauses or delays
|
||||||
|
- Database slowness
|
||||||
|
|
||||||
|
**Common causes:**
|
||||||
|
- Database taking time to initialize
|
||||||
|
- Blockchain recording many elections
|
||||||
|
- Network latency
|
||||||
|
|
||||||
|
## Files Reference
|
||||||
|
|
||||||
|
### Logging Configuration
|
||||||
|
- **`backend/logging_config.py`** - Central logging setup, colors, emojis, levels
|
||||||
|
|
||||||
|
### Modules with Logging
|
||||||
|
- **`backend/main.py`** - Startup sequence logging
|
||||||
|
- **`backend/init_blockchain.py`** - Blockchain initialization logging
|
||||||
|
- **`backend/services.py`** - Service operation logging
|
||||||
|
- **`backend/database.py`** - Database operation logging
|
||||||
|
- **`backend/routes/*.py`** - API endpoint logging (future)
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
- **`LOGGING_GUIDE.md`** - Complete logging guide with examples
|
||||||
|
- **`BACKEND_STARTUP_GUIDE.md`** - Startup troubleshooting
|
||||||
|
- **`BLOCKCHAIN_ELECTION_INTEGRATION.md`** - Blockchain details
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
1. **Run the backend:**
|
||||||
|
```bash
|
||||||
|
docker compose up -d backend
|
||||||
|
sleep 30
|
||||||
|
docker compose logs backend
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Watch for logs:**
|
||||||
|
- Look for "✓" (success) in startup
|
||||||
|
- Check for "blockchain" activity
|
||||||
|
- Verify "integrity verified"
|
||||||
|
|
||||||
|
3. **Test the system:**
|
||||||
|
```bash
|
||||||
|
python3 test_blockchain_election.py
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Monitor in production:**
|
||||||
|
- Set up log rotation (future)
|
||||||
|
- Send logs to centralized system (ELK, Splunk, etc.)
|
||||||
|
- Create alerts for errors
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
The logging system provides:
|
||||||
|
|
||||||
|
✓ **Clear visibility** into system operations
|
||||||
|
✓ **Structured information** with timestamps and modules
|
||||||
|
✓ **Color-coded output** for easy scanning
|
||||||
|
✓ **Emoji prefixes** for quick identification
|
||||||
|
✓ **Full exception details** for debugging
|
||||||
|
✓ **Performance insights** from timing information
|
||||||
|
✓ **Multi-node support** for load-balanced systems
|
||||||
|
|
||||||
|
This enables:
|
||||||
|
- Quick problem identification
|
||||||
|
- Faster debugging and resolution
|
||||||
|
- Better understanding of system behavior
|
||||||
|
- Performance monitoring and optimization
|
||||||
|
- Historical logs for analysis and auditing
|
||||||
Loading…
x
Reference in New Issue
Block a user