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
nparameter 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=Xfor 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
nparameter 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, ...)
