sql-xel-parser 1.0.0__py3-none-any.whl

sql_xel_parser/cli.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""
+XEL Parser CLI - Command-line interface for XEL file parsing and analysis.
+"""
+
+import argparse
+import sys
+import json
+from pathlib import Path
+from typing import Optional, List
+
+from .parser import XELParser
+from .converter import XELConverter
+from .analyzer import XELAnalyzer
+
+
+def parse_args():
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        prog='xel-parser',
+        description='Parse and analyze SQL Server Extended Events (.xel) files',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Convert XEL to JSON
+  xel-parser input.xel -o output.json -f json
+
+  # Convert to readable text
+  xel-parser input.xel -o output.txt -f text
+
+  # Process entire directory (recursively)
+  xel-parser data/sql-ptfm-prod-westus3 -r -o merged_output.json
+
+  # Process folder and get summary
+  xel-parser data/sql-ptfm-prod-westus3 -r -f summary
+
+  # Filter events by name
+  xel-parser input.xel -o output.json --filter-name "sql_batch_completed"
+
+  # Search for specific content
+  xel-parser input.xel -o results.json --search "SELECT.*FROM"
+
+  # Get summary statistics
+  xel-parser input.xel -f summary
+
+  # Count events by type
+  xel-parser input.xel --count-by name
+
+  # Get top 10 queries by duration
+  xel-parser input.xel --filter-field "data.duration" --top-n "data.duration" 10
+        """
+    )
+
+    parser.add_argument('input', help='Input XEL file or directory path')
+    parser.add_argument('-o', '--output', help='Output file path (default: stdout)')
+    parser.add_argument('-f', '--format',
+                       choices=['json', 'jsonl', 'csv', 'text', 'markdown', 'md', 'summary'],
+                       default='json',
+                       help='Output format (default: json)')
+    parser.add_argument('-r', '--recursive', action='store_true',
+                       help='Recursively search for XEL files in directory')
+    parser.add_argument('--merge', action='store_true', default=True,
+                       help='Merge all events from multiple files (default: True)')
+    parser.add_argument('--separate', dest='merge', action='store_false',
+                       help='Process each file separately (outputs to multiple files)')
+
+    # Filtering options
+    filter_group = parser.add_argument_group('filtering options')
+    filter_group.add_argument('--filter-name', metavar='PATTERN',
+                             help='Filter events by name (regex supported)')
+    filter_group.add_argument('--filter-field', metavar='FIELD=VALUE',
+                             action='append',
+                             help='Filter by field value (e.g., data.duration>1000)')
+    filter_group.add_argument('--filter-time-start', metavar='TIMESTAMP',
+                             help='Filter events after this timestamp')
+    filter_group.add_argument('--filter-time-end', metavar='TIMESTAMP',
+                             help='Filter events before this timestamp')
+    filter_group.add_argument('--search', metavar='QUERY',
+                             help='Search events for query string (regex supported)')
+
+    # Analysis options
+    analysis_group = parser.add_argument_group('analysis options')
+    analysis_group.add_argument('--stats', action='store_true',
+                               help='Show statistics about events')
+    analysis_group.add_argument('--count-by', metavar='FIELD',
+                               help='Count events by field value')
+    analysis_group.add_argument('--group-by', metavar='FIELD',
+                               help='Group events by field value')
+    analysis_group.add_argument('--top-n', metavar='FIELD:N',
+                               help='Show top N values by frequency (e.g., name:10)')
+    analysis_group.add_argument('--aggregate', metavar='FIELD:OP',
+                               help='Aggregate field (ops: count,sum,avg,min,max,distinct)')
+
+    # Output options
+    parser.add_argument('--verbose', action='store_true',
+                       help='Verbose output (for text format)')
+    parser.add_argument('--indent', type=int, default=2,
+                       help='JSON indentation level (default: 2)')
+    parser.add_argument('--limit', type=int,
+                       help='Limit number of events to process')
+    parser.add_argument('--version', action='version', version='%(prog)s 1.0.0')
+
+    return parser.parse_args()
+
+
+def find_xel_files(path: Path, recursive: bool = False) -> List[Path]:
+    """Find all XEL files in a directory."""
+    if path.is_file():
+        return [path]
+
+    if recursive:
+        xel_files = list(path.rglob('*.xel'))
+    else:
+        xel_files = list(path.glob('*.xel'))
+
+    xel_files.sort(key=lambda p: p.stat().st_mtime)
+    return xel_files
+
+
+def parse_xel_files(file_paths: List[Path], limit: Optional[int] = None):
+    """Parse multiple XEL files and merge events."""
+    all_events = []
+    total_files = len(file_paths)
+
+    for i, file_path in enumerate(file_paths, 1):
+        try:
+            print(f"Parsing file {i}/{total_files}: {file_path}", file=sys.stderr)
+            parser = XELParser(str(file_path))
+            events = list(parser.parse())
+            print(f"  Found {len(events)} events", file=sys.stderr)
+            all_events.extend(events)
+
+            if limit and len(all_events) >= limit:
+                print(f"Reached event limit of {limit}, stopping", file=sys.stderr)
+                all_events = all_events[:limit]
+                break
+
+        except Exception as e:
+            print(f"  Error parsing {file_path}: {e}", file=sys.stderr)
+            continue
+
+    return all_events
+
+
+def apply_filters(analyzer: XELAnalyzer, args) -> XELAnalyzer:
+    """Apply all filters from command-line arguments."""
+    if args.filter_name:
+        analyzer = analyzer.filter_by_name(args.filter_name)
+        print(f"After name filter: {len(analyzer.events)} events", file=sys.stderr)
+
+    if args.filter_time_start or args.filter_time_end:
+        analyzer = analyzer.filter_by_time_range(args.filter_time_start, args.filter_time_end)
+        print(f"After time filter: {len(analyzer.events)} events", file=sys.stderr)
+
+    if args.filter_field:
+        for field_filter in args.filter_field:
+            analyzer = apply_field_filter(analyzer, field_filter)
+            print(f"After field filter '{field_filter}': {len(analyzer.events)} events", file=sys.stderr)
+
+    if args.search:
+        analyzer = analyzer.search(args.search)
+        print(f"After search '{args.search}': {len(analyzer.events)} events", file=sys.stderr)
+
+    return analyzer
+
+
+def apply_field_filter(analyzer: XELAnalyzer, filter_str: str) -> XELAnalyzer:
+    """Parse and apply a field filter."""
+    operators = {
+        '>=': 'gte',
+        '<=': 'lte',
+        '>': 'gt',
+        '<': 'lt',
+        '=': 'equals',
+        '~': 'contains',
+    }
+
+    for op_str, op_name in operators.items():
+        if op_str in filter_str:
+            field, value = filter_str.split(op_str, 1)
+            field = field.strip()
+            value = value.strip()
+
+            try:
+                value = int(value)
+            except ValueError:
+                try:
+                    value = float(value)
+                except ValueError:
+                    pass
+
+            return analyzer.filter_by_field(field, value, op_name)
+
+    return analyzer.filter_by_field(filter_str.strip(), operator='exists')
+
+
+def perform_analysis(analyzer: XELAnalyzer, args):
+    """Perform analysis and output results."""
+    if args.stats:
+        stats = analyzer.get_stats()
+        print(json.dumps(stats, indent=args.indent))
+        return True
+
+    if args.count_by:
+        counts = analyzer.count_by(args.count_by)
+        print(json.dumps(counts, indent=args.indent))
+        return True
+
+    if args.group_by:
+        groups = analyzer.group_by(args.group_by)
+        result = {k: len(v) for k, v in groups.items()}
+        print(json.dumps(result, indent=args.indent))
+        return True
+
+    if args.top_n:
+        parts = args.top_n.split(':')
+        field = parts[0]
+        n = int(parts[1]) if len(parts) > 1 else 10
+        top_values = analyzer.top_n(field, n)
+        print(json.dumps(dict(top_values), indent=args.indent))
+        return True
+
+    if args.aggregate:
+        parts = args.aggregate.split(':')
+        field = parts[0]
+        operation = parts[1] if len(parts) > 1 else 'count'
+        result = analyzer.aggregate(field, operation)
+        print(json.dumps(result, indent=args.indent))
+        return True
+
+    return False
+
+
+def main():
+    """Main entry point."""
+    args = parse_args()
+
+    input_path = Path(args.input)
+    if not input_path.exists():
+        print(f"Error: Input path not found: {args.input}", file=sys.stderr)
+        return 1
+
+    try:
+        if input_path.is_dir():
+            print(f"Searching for XEL files in {args.input}...", file=sys.stderr)
+            xel_files = find_xel_files(input_path, recursive=args.recursive)
+            if not xel_files:
+                print("Error: No XEL files found in directory", file=sys.stderr)
+                return 1
+            print(f"Found {len(xel_files)} XEL files", file=sys.stderr)
+
+            events = parse_xel_files(xel_files, limit=args.limit)
+            print(f"\nTotal events from all files: {len(events)}", file=sys.stderr)
+        else:
+            print(f"Parsing {args.input}...", file=sys.stderr)
+            parser = XELParser(str(input_path))
+            events = list(parser.parse())
+            print(f"Parsed {len(events)} events", file=sys.stderr)
+
+            if args.limit:
+                events = events[:args.limit]
+                print(f"Limited to {len(events)} events", file=sys.stderr)
+
+        if not events:
+            print("Warning: No events found", file=sys.stderr)
+            return 0
+
+        analyzer = XELAnalyzer(events)
+
+        if any([args.filter_name, args.filter_field, args.filter_time_start,
+                args.filter_time_end, args.search]):
+            analyzer = apply_filters(analyzer, args)
+            events = analyzer.get_events()
+
+        if perform_analysis(analyzer, args):
+            return 0
+
+        converter = XELConverter()
+
+        if args.format == 'json':
+            output = converter.to_json(events, indent=args.indent)
+        elif args.format == 'jsonl':
+            output = converter.to_json_lines(events)
+        elif args.format == 'csv':
+            output = converter.to_csv(events)
+        elif args.format == 'text':
+            output = converter.to_text(events, verbose=args.verbose)
+        elif args.format in ('markdown', 'md'):
+            output = converter.to_markdown(events)
+        elif args.format == 'summary':
+            output = converter.to_summary(events)
+        else:
+            print(f"Error: Unsupported format: {args.format}", file=sys.stderr)
+            return 1
+
+        if args.output:
+            output_path = Path(args.output)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(output_path, 'w', encoding='utf-8') as f:
+                f.write(output)
+            print(f"Output written to {args.output}", file=sys.stderr)
+        else:
+            print(output)
+
+        return 0
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        import traceback
+        traceback.print_exc(file=sys.stderr)
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

sql_xel_parser/converter.py

@@ -0,0 +1,284 @@
+"""
+XEL Converter - Convert parsed XEL events to various human-readable formats.
+
+Supported formats:
+- JSON
+- CSV
+- Pretty text
+- Markdown
+"""
+
+import json
+import csv
+from typing import List, Dict, Any, TextIO
+from datetime import datetime
+
+
+class XELConverter:
+    """Converter for XEL events to various formats."""
+
+    @staticmethod
+    def to_json(events: List[Dict[str, Any]], indent: int = 2) -> str:
+        """
+        Convert events to JSON format.
+
+        Args:
+            events: List of event dictionaries
+            indent: JSON indentation level
+
+        Returns:
+            JSON string
+        """
+        return json.dumps(events, indent=indent, default=str)
+
+    @staticmethod
+    def to_json_lines(events: List[Dict[str, Any]]) -> str:
+        """
+        Convert events to JSON Lines format (one JSON object per line).
+
+        Args:
+            events: List of event dictionaries
+
+        Returns:
+            JSON Lines string
+        """
+        lines = []
+        for event in events:
+            lines.append(json.dumps(event, default=str))
+        return '\n'.join(lines)
+
+    @staticmethod
+    def to_csv(events: List[Dict[str, Any]]) -> str:
+        """
+        Convert events to CSV format.
+
+        Args:
+            events: List of event dictionaries
+
+        Returns:
+            CSV string
+        """
+        if not events:
+            return ""
+
+        # Flatten events and collect all possible fields
+        flattened_events = []
+        all_fields = set()
+
+        for event in events:
+            flat_event = XELConverter._flatten_dict(event)
+            flattened_events.append(flat_event)
+            all_fields.update(flat_event.keys())
+
+        # Sort fields for consistent output
+        fieldnames = sorted(all_fields)
+
+        # Write to CSV
+        import io
+        output = io.StringIO()
+        writer = csv.DictWriter(output, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(flattened_events)
+
+        return output.getvalue()
+
+    @staticmethod
+    def to_text(events: List[Dict[str, Any]], verbose: bool = True) -> str:
+        """
+        Convert events to pretty text format.
+
+        Args:
+            events: List of event dictionaries
+            verbose: Include all details
+
+        Returns:
+            Formatted text string
+        """
+        lines = []
+        lines.append("=" * 80)
+        lines.append(f"XEL Events Report - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+        lines.append(f"Total Events: {len(events)}")
+        lines.append("=" * 80)
+        lines.append("")
+
+        for i, event in enumerate(events, 1):
+            lines.append(f"Event #{i}: {event.get('name', 'Unknown')}")
+            lines.append("-" * 80)
+
+            if event.get('timestamp'):
+                lines.append(f"  Timestamp: {event['timestamp']}")
+
+            if verbose and event.get('data'):
+                lines.append(f"  Data:")
+                for key, value in event['data'].items():
+                    lines.append(f"    {key}: {value}")
+
+            if verbose and event.get('actions'):
+                lines.append(f"  Actions:")
+                for key, value in event['actions'].items():
+                    lines.append(f"    {key}: {value}")
+
+            if event.get('content'):
+                lines.append(f"  Content: {event['content']}")
+
+            lines.append("")
+
+        return '\n'.join(lines)
+
+    @staticmethod
+    def to_markdown(events: List[Dict[str, Any]]) -> str:
+        """
+        Convert events to Markdown format.
+
+        Args:
+            events: List of event dictionaries
+
+        Returns:
+            Markdown string
+        """
+        lines = []
+        lines.append("# XEL Events Report")
+        lines.append("")
+        lines.append(f"**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+        lines.append(f"**Total Events:** {len(events)}")
+        lines.append("")
+
+        for i, event in enumerate(events, 1):
+            lines.append(f"## Event {i}: {event.get('name', 'Unknown')}")
+            lines.append("")
+
+            if event.get('timestamp'):
+                lines.append(f"**Timestamp:** `{event['timestamp']}`")
+                lines.append("")
+
+            if event.get('data'):
+                lines.append("### Data")
+                lines.append("")
+                for key, value in event['data'].items():
+                    lines.append(f"- **{key}:** `{value}`")
+                lines.append("")
+
+            if event.get('actions'):
+                lines.append("### Actions")
+                lines.append("")
+                for key, value in event['actions'].items():
+                    lines.append(f"- **{key}:** `{value}`")
+                lines.append("")
+
+            if event.get('content'):
+                lines.append("### Content")
+                lines.append("")
+                lines.append(f"```")
+                lines.append(str(event['content']))
+                lines.append(f"```")
+                lines.append("")
+
+            lines.append("---")
+            lines.append("")
+
+        return '\n'.join(lines)
+
+    @staticmethod
+    def to_summary(events: List[Dict[str, Any]]) -> str:
+        """
+        Generate a summary of events.
+
+        Args:
+            events: List of event dictionaries
+
+        Returns:
+            Summary string
+        """
+        if not events:
+            return "No events found."
+
+        # Count events by name
+        event_counts = {}
+        for event in events:
+            name = event.get('name', 'Unknown')
+            event_counts[name] = event_counts.get(name, 0) + 1
+
+        # Get time range
+        timestamps = [e.get('timestamp', '') for e in events if e.get('timestamp')]
+        time_range = "Unknown"
+        if timestamps:
+            try:
+                timestamps.sort()
+                time_range = f"{timestamps[0]} to {timestamps[-1]}"
+            except:
+                pass
+
+        lines = []
+        lines.append("XEL Events Summary")
+        lines.append("=" * 80)
+        lines.append(f"Total Events: {len(events)}")
+        lines.append(f"Time Range: {time_range}")
+        lines.append("")
+        lines.append("Event Types:")
+        for name, count in sorted(event_counts.items(), key=lambda x: x[1], reverse=True):
+            lines.append(f"  {name}: {count}")
+
+        return '\n'.join(lines)
+
+    @staticmethod
+    def _flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '_') -> Dict[str, Any]:
+        """
+        Flatten a nested dictionary.
+
+        Args:
+            d: Dictionary to flatten
+            parent_key: Parent key prefix
+            sep: Separator for nested keys
+
+        Returns:
+            Flattened dictionary
+        """
+        items = []
+        for k, v in d.items():
+            new_key = f"{parent_key}{sep}{k}" if parent_key else k
+            if isinstance(v, dict):
+                items.extend(XELConverter._flatten_dict(v, new_key, sep=sep).items())
+            else:
+                items.append((new_key, v))
+        return dict(items)
+
+
+def convert_file(input_path: str, output_path: str, format: str, **kwargs):
+    """
+    Convenience function to convert an XEL file to a specific format.
+
+    Args:
+        input_path: Path to input XEL file
+        output_path: Path to output file
+        format: Output format (json, jsonl, csv, text, markdown, summary)
+        **kwargs: Additional arguments for conversion
+    """
+    from xel_parser import XELParser
+
+    # Parse events
+    parser = XELParser(input_path)
+    events = list(parser.parse())
+
+    # Convert to specified format
+    converter = XELConverter()
+
+    if format == 'json':
+        output = converter.to_json(events, indent=kwargs.get('indent', 2))
+    elif format == 'jsonl':
+        output = converter.to_json_lines(events)
+    elif format == 'csv':
+        output = converter.to_csv(events)
+    elif format == 'text':
+        output = converter.to_text(events, verbose=kwargs.get('verbose', True))
+    elif format == 'markdown' or format == 'md':
+        output = converter.to_markdown(events)
+    elif format == 'summary':
+        output = converter.to_summary(events)
+    else:
+        raise ValueError(f"Unsupported format: {format}")
+
+    # Write output
+    with open(output_path, 'w', encoding='utf-8') as f:
+        f.write(output)
+
+    return len(events)