Quick Start
Core Features
Log Filtering
Filter log entries using multiple criteria:Scenario Conversion for Analysis
Convert log entries to EDSL scenarios for advanced analysis:timestamp_str
: Formatted timestamp - logger_name
: Full logger name - logger_module
: Last part of logger name - level
: Log level (ERROR, INFO, etc.) - level_int
: Numeric level for comparison - message
: Log message content - raw_line
: Original log line - hour
, minute
, weekday
: Time components - date_str
: Date in YYYY-MM-DD format - is_error
: Boolean for ERROR/CRITICAL levels - is_warning_or_above
: Boolean for WARNING+ levels - has_exception
: Boolean if message contains “exception” - has_failed
: Boolean if message contains “fail” - message_length
: Character count of message - words_count
: Word count of message
Using Log Scenarios with EDSL
Analyze log entries using EDSL questions:Pattern Analysis
Extract insights from log patterns:Statistics and Reporting
Get comprehensive statistics about your logs:Export and Sharing
Export filtered logs or share via Coop:Log Maintenance
Archive Logs
Create timestamped backups of your logs:Clear Logs
Remove all log entries to start fresh:Advanced Usage
Custom Log Files
Work with non-default log files:Filtering Best Practices
Combine filters for precise results:Performance Optimization
LogManager automatically caches statistics for better performance:Integration Examples
Debugging Workflows
Monitoring Automation
Research and Analysis
Jupyter Notebook Integration
LogManager provides rich HTML displays in Jupyter notebooks:API Reference
LogManager Class
class LogManager(log_file_path=None)Main class for EDSL log management.
Parameters | log_file_path (Path*,* optional) – Optional path to log file. Defaults to ~/.edsl/logs/edsl.log |
get_filtered_entries(**kwargs)Filter log entries by various criteria.
Parameters | • n (int*,* optional) – Maximum number of entries to return • level (str or List*[str]**,* optional) – Specific level(s) to include (‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’) • min_level (str*,* optional) – Minimum level (includes this level and above) • since_hours (float*,* optional) – Include entries from last N hours • since_minutes (float*,* optional) – Include entries from last N minutes • start_date (str or datetime*,* optional) – Start date for filtering (‘YYYY-MM-DD’) • end_date (str or datetime*,* optional) – End date for filtering (‘YYYY-MM-DD’) • pattern (str*,* optional) – Regex pattern for message content • logger_pattern (str*,* optional) – Regex pattern for logger names • case_sensitive (bool*,* optional) – Whether pattern matching is case sensitive • reverse (bool*,* optional) – Return in reverse chronological order |
Returns | List of filtered log entries |
Return type | List[LogEntry] |
to_scenario_list(entries=None, **filter_kwargs)Convert log entries to EDSL scenarios.
Parameters | • entries (List*[LogEntry]**,* optional) – Pre-filtered entries to convert • filter_kwargs – Arguments for get_filtered_entries() |
Returns | ScenarioList with log data |
Return type | ScenarioList |
analyze_patterns(**filter_kwargs)Analyze log patterns and extract insights.
Parameters | • filter_kwargs – Arguments for get_filtered_entries() |
Returns | Dictionary with pattern analysis |
Return type | Dict[str, Any] |
get_stats(entries=None)Get statistics about log entries.
Parameters | • entries (List*[LogEntry]**,* optional) – Specific entries to analyze |
Returns | Statistics dictionary |
Return type | Dict[str, Any] |
export_filtered_logs(output_path, **filter_kwargs)Export filtered log entries to file.
Parameters | • output_path (Path) – Path for output file • filter_kwargs – Arguments for get_filtered_entries() |
Returns | Number of entries exported |
Return type | int |
archive(archive_path=None, clear_after_archive=True, compress=True, confirm=False)Archive log file with timestamp.
Parameters | • archive_path (Path*,* optional) – Directory for archive (default: ~/.edsl/archives/) • clear_after_archive (bool) – Clear original after archiving • compress (bool) – Gzip compress the archive • confirm (bool) – Skip confirmation prompt |
Returns | Path to created archive |
Return type | Path or None |
clear(confirm=False)Clear all log entries.
Parameters | • confirm (bool) – Skip confirmation prompt |
Returns | Success status |
Return type | bool |
LogEntry Class
class LogEntryRepresents a parsed log entry.
Parameters | • timestamp (datetime) – When the log entry was created • logger_name (str) – Name of the logger • level (str) – Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) • message (str) – Log message content • raw_line (str) – Original log line • level_int (int) – Numeric level for comparisons |
Best Practices
Safety Guidelines
- Always use confirmation prompts for destructive operations (default behavior)
- Archive logs before clearing in production environments
- Use specific filters to avoid processing unnecessary log entries
- Test complex regex patterns with small datasets first
Performance Tips
- Use
n
parameter to limit results when exploring large logs - Combine multiple filters in single calls rather than chaining
- Cache LogManager instances when doing multiple operations
- Consider archiving very large log files before analysis
Common Patterns
Error Investigation:- Filter recent errors:
get_filtered_entries(level='ERROR', since_hours=24)
- Convert to scenarios for analysis:
to_scenario_list()
- Use EDSL questions to categorize and analyze
- Export findings or share via Coop
- Weekly archive:
archive()
(includes clearing) - Monitor critical issues:
get_filtered_entries(level='CRITICAL')
- Pattern analysis:
analyze_patterns()
for trends
- Filter by component:
logger_pattern='component_name'
- Time-bound investigation:
since_hours=X
for specific incidents - Pattern matching:
pattern='specific_error_text'
- Export for sharing:
export_filtered_logs()
Troubleshooting
Common Issues
Log file not found: Check the log file path. EDSL logs are typically at~/.edsl/logs/edsl.log
No entries returned:
- Verify log file has content:
log_manager.get_stats()
- Check filter criteria are not too restrictive
- Ensure date ranges are correct
- Use
n
parameter to limit results - Consider archiving old entries
- Filter by time ranges first, then other criteria
- Ensure read access to log file
- For archive/clear operations, ensure write access to log directory
Getting Help
- View available commands:
print(log_manager)
- Check method documentation:
help(log_manager.method_name)
- View log overview:
log_manager.get_stats()
- Test filters with small limits:
get_filtered_entries(n=10, ...)