Implement comprehensive professional logging system

Added complete logging infrastructure for AI-only development debugging:

**Core Logging Features:**
- Command-line debug flags: -d (console) and -d filename (file output)
- Custom log format: "message - severity - timestamp"
- Professional Python logging with hierarchical loggers (bifrost.module)
- Clean separation: debug mode vs production (warnings/errors only)

**Comprehensive Coverage - Replaced 55+ Print Statements:**
- timeline_view.py: Timeline operations, new content detection, sound events
- main_window.py: Auto-refresh system, streaming mode, UI events
- activitypub/client.py: API calls, streaming connections, server detection
- audio/sound_manager.py: Sound playback, pack loading, volume control
- error_manager.py: Centralized error handling with proper log levels
- All remaining modules: Complete print statement elimination

**Enhanced Auto-Refresh Debugging:**
- Fixed repetitive refresh interval logging (only logs on changes)
- Added detailed auto-refresh execution tracing with timing
- New content detection logging with post ID tracking
- Sound event logging showing which sounds play and why

**Sound System Visibility:**
- Complete audio event logging with file paths and volumes
- Sound pack loading and fallback detection
- Audio playback success/failure with detailed error context

**Documentation Updates:**
- README.md: Complete debug system documentation for users
- CLAUDE.md: Professional logging guidelines for AI development
- Comprehensive usage examples and troubleshooting guides

This logging system provides essential debugging capabilities for
the AI-only development constraint, enabling systematic issue
resolution without human code intervention.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Storm Dragon
2025-07-22 23:32:55 -04:00
parent 3c45932fea
commit 8b9187e23f
22 changed files with 1918 additions and 238 deletions

View File

@ -75,6 +75,86 @@ When adding event-driven features, always test:
- Window closing during operations
- Tab switching with keyboard vs mouse
## Professional Logging System
Bifrost includes a comprehensive logging system essential for AI-only development. All debugging should use proper logging instead of print statements.
### Logging Standards
**Command-line Debug Flags:**
- `python bifrost.py -d` - Debug output to console
- `python bifrost.py -d filename` - Debug output to file
- `python bifrost.py` - Production mode (warnings/errors only)
**Log Format:** `message - severity - timestamp`
```
Timeline refresh requested: auto_refresh - DEBUG - 2025-07-22 23:17:33
New content detected: newest post changed from abc123 to def456 - INFO - 2025-07-22 23:17:34
```
### Logger Setup Pattern
Every class should have a logger in `__init__()`:
```python
import logging
class MyClass:
def __init__(self):
self.logger = logging.getLogger('bifrost.module_name')
```
### Logging Guidelines
**What to Log at Each Level:**
- **DEBUG**: Method calls, state changes, timing information, execution flow
- **INFO**: Important events (new content detected, sounds played, operations completed)
- **WARNING**: Recoverable issues (fallbacks, missing optional features, server incompatibilities)
- **ERROR**: Serious problems (network failures, invalid data, system errors)
- **CRITICAL**: Fatal issues that prevent operation
**Required Logging Areas:**
1. **Auto-refresh System**: Timing, triggers, new content detection
2. **Sound Events**: Which sounds played, when, and why
3. **Network Operations**: API calls, streaming connections, failures
4. **User Actions**: Post composition, timeline navigation, settings changes
5. **Error Conditions**: All exceptions, fallbacks, and recovery attempts
**Logging Patterns:**
```python
# Method entry/exit for complex operations
self.logger.debug("method_name() called")
self.logger.debug("method_name() completed successfully")
# State changes
self.logger.info(f"Timeline switched from {old} to {new}")
# New content detection
self.logger.info(f"New content detected: {count} new posts")
# Sound events
self.logger.info(f"Playing {sound_type} sound for {reason}")
# Error handling with context
self.logger.error(f"Failed to {operation}: {error}")
```
**Never Use Print Statements:**
- All output should go through the logging system
- Print statements interfere with proper log formatting
- Use appropriate log levels instead of printing debug info
### AI Development Benefits
This logging system is crucial for AI-only development because:
- Provides complete visibility into application behavior
- Enables systematic debugging without human intervention
- Shows exact timing and causation of events
- Facilitates troubleshooting of complex interactions
- Maintains clean separation between debug and production modes
## Documentation and Dependencies
- **README Updates**: When adding new functionality or sound events, update README.md with detailed descriptions
- **Requirements Management**: Check and update requirements.txt when new dependencies are added