Logging: Log File Parsing and Inspection Tools (Medium Priority)

[jwesleye]

Overview

Add log file parsing and inspection tools to help agents analyze logs without loading entire files into context.

Motivation

Log files can be massive (thousands or millions of lines). Agents often need to extract errors, filter by timestamp, or sample entries without loading entire log files. This complements the existing structured logging tools.

Proposed Functions

High Priority - Parsing

• parse_log_entries - Parse structured logs (JSON logs, syslog, common formats)
• detect_log_format - Auto-detect log format from sample lines
• extract_log_fields - Extract specific fields from log entries

High Priority - Filtering

• filter_log_entries - Filter by level, timestamp range, message pattern
• get_log_errors - Extract only ERROR/CRITICAL entries
• search_log_messages - Search for pattern in messages (regex support)

Medium Priority - Analysis

• get_log_summary - Count entries by level, time distribution
• sample_log_entries - Random sample of entries (first/random/systematic)
• get_log_time_range - Get earliest and latest timestamps
• count_log_entries - Count entries with optional filter

Lower Priority - Advanced

• group_log_entries - Group entries by field (timestamp bucket, level, etc.)
• tail_log_file - Get last N entries efficiently
• extract_log_errors_context - Get errors with surrounding context lines

Supported Formats

• JSON logs (one JSON object per line)
• Syslog format
• Common log format (CLF)
• Custom delimiter-based formats
• Python logging format
• Generic key=value formats

Design Principles

• Google ADK compliant (JSON-serializable types, no defaults)
• @strands_tool decorator
• Memory-efficient (streaming, never load entire file)
• Support multiple log formats
• Consistent with CSV/JSON token-saving patterns
• Return structured data (list of dicts)

Related

• Extends existing logging/ module (structured.py, rotation.py)
• Similar to CSV tools pattern: filter_csv_rows, sample_csv_rows, count_csv_rows
• Related to issue Data: Future Enhancement Features #57 (Data Future Enhancements)

Module

logging/parsing.py (new file)