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