Update observability docs and task utilities

- Add Observability.md documentation
- Standardize task logging with correlation_id support
- Add log_sanitizer utility for PII masking
- Update Tasks.md tracking
- Update geo_cache tasks and other task modules with correlation_id

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
2026-05-03 11:52:09 +02:00
parent 7b93499551
commit 0133489920
17 changed files with 582 additions and 124 deletions

View File

@@ -1,103 +1,3 @@
### Issue #18: MEDIUM - Configuration Validation Missing at Startup
**Where found**:
- `backend/app/config.py` (lines 37-95)
- `database_path` has no validation
- `fail2ban_socket` not verified to exist
- Hard-coded paths assumed in Docker
**Why this is needed**:
Configuration errors not caught at startup:
- Database path doesn't exist - fails on first DB operation (confusing error)
- fail2ban socket wrong path - only fails when health check runs
- Directory not writable - discovered hours after deployment
**Goal**:
Validate all configuration at startup with clear error messages.
**What to do**:
1. Add validators to config fields:
```python
@field_validator("database_path")
def validate_db_path(cls, v):
path = Path(v)
parent = path.parent
if not parent.exists():
raise ValueError(
f"Database parent directory does not exist: {parent}\n"
f"Create it with: mkdir -p {parent}"
)
if not os.access(parent, os.W_OK):
raise ValueError(
f"Database directory not writable: {parent}\n"
f"Fix with: chmod 755 {parent}"
)
return v
```
2. Validate fail2ban socket exists and is readable
3. Verify session secret is sufficiently long
4. Check environment variables are set
5. Provide actionable error messages
**Possible traps and issues**:
- Validation might be too strict for some deployments
- Need to handle cases where files don't exist yet but will be created
- Docker initialization order might delay file creation
**Docs changes needed**:
- Document required directories and permissions
- Create setup validation troubleshooting guide
**Doc references**:
- DATABASE_API_DEPLOYMENT_ISSUES.md - Issue "5.2 Missing Configuration Validation"
---
### Issue #19: MEDIUM - Sensitive Data Could Leak in Logs
**Where found**:
- `backend/app/utils/fail2ban_client.py` (line 148) - Logs subprocess output without sanitization
- Could contain passwords, API keys from config files
**Why this is needed**:
If subprocess output contains secrets, logs become security liability and violate compliance requirements.
**Goal**:
Sanitize logs to remove sensitive information patterns.
**What to do**:
1. Create sanitizer function:
```python
def sanitize_for_logging(text: str) -> str:
# Remove passwords
text = re.sub(r'password[=:]\S+', 'password=***', text, flags=re.IGNORECASE)
# Remove API keys
text = re.sub(r'api[_-]?key[=:]\S+', 'api_key=***', text, flags=re.IGNORECASE)
# Remove tokens
text = re.sub(r'token[=:]\S+', 'token=***', text, flags=re.IGNORECASE)
return text
```
2. Apply to all subprocess output and external responses
3. Add to logging middleware
4. Audit existing logs for sensitive data
**Possible traps and issues**:
- Patterns might miss some sensitive data formats
- Over-sanitization might hide helpful debug info
- Performance cost if sanitizing large outputs
**Docs changes needed**:
- Add logging best practices guide
- Document what's sanitized
**Doc references**:
- DETAILED_FINDINGS.md - Issue #25 "Sensitive Data in Logs"
---
### Issue #20: MEDIUM - No Correlation ID in Background Tasks
**Where found**: