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

sql_xel_parser/__init__.py

@@ -0,0 +1,14 @@
+"""
+XEL Parser - Parse and analyze SQL Server Extended Events files.
+
+A Python package for parsing and analyzing SQL Server Extended Events (.xel) files
+without requiring SQL Server.
+"""
+
+from .parser import XELParser
+from .converter import XELConverter
+from .analyzer import XELAnalyzer
+from .real_parser import parse_xel_file, extract_real_data_from_xel
+
+__version__ = '1.0.0'
+__all__ = ['XELParser', 'XELConverter', 'XELAnalyzer', 'parse_xel_file', 'extract_real_data_from_xel']

sql_xel_parser/__main__.py

@@ -0,0 +1,6 @@
+"""Allow package to be run as python -m xel_parser"""
+
+from .cli import main
+
+if __name__ == '__main__':
+    main()

sql_xel_parser/analyzer.py

@@ -0,0 +1,380 @@
+"""
+XEL Analyzer - Advanced parsing, filtering, and analysis of XEL events.
+
+Provides utilities for:
+- Filtering events by various criteria
+- Searching event content
+- Aggregating and grouping events
+- Statistical analysis
+"""
+
+import re
+from typing import List, Dict, Any, Callable, Optional
+from datetime import datetime
+from collections import defaultdict
+
+
+class XELAnalyzer:
+    """Analyzer for XEL events with filtering and aggregation capabilities."""
+
+    def __init__(self, events: List[Dict[str, Any]]):
+        """
+        Initialize analyzer with events.
+
+        Args:
+            events: List of parsed event dictionaries
+        """
+        self.events = events
+
+    def filter_by_name(self, name_pattern: str) -> 'XELAnalyzer':
+        """
+        Filter events by name pattern.
+
+        Args:
+            name_pattern: Regex pattern or exact name
+
+        Returns:
+            New XELAnalyzer with filtered events
+        """
+        try:
+            pattern = re.compile(name_pattern, re.IGNORECASE)
+            filtered = [e for e in self.events if pattern.search(e.get('name', ''))]
+        except re.error:
+            # If regex fails, try exact match
+            filtered = [e for e in self.events if e.get('name', '') == name_pattern]
+
+        return XELAnalyzer(filtered)
+
+    def filter_by_time_range(self, start_time: Optional[str] = None,
+                            end_time: Optional[str] = None) -> 'XELAnalyzer':
+        """
+        Filter events by time range.
+
+        Args:
+            start_time: Start timestamp (ISO format or parseable string)
+            end_time: End timestamp (ISO format or parseable string)
+
+        Returns:
+            New XELAnalyzer with filtered events
+        """
+        filtered = []
+        for event in self.events:
+            timestamp = event.get('timestamp', '')
+            if not timestamp:
+                continue
+
+            # Convert timestamp to comparable format
+            try:
+                event_time = self._parse_timestamp(timestamp)
+            except:
+                continue
+
+            # Check range
+            if start_time:
+                try:
+                    start = self._parse_timestamp(start_time)
+                    if event_time < start:
+                        continue
+                except:
+                    pass
+
+            if end_time:
+                try:
+                    end = self._parse_timestamp(end_time)
+                    if event_time > end:
+                        continue
+                except:
+                    pass
+
+            filtered.append(event)
+
+        return XELAnalyzer(filtered)
+
+    def filter_by_field(self, field_path: str, value: Any = None,
+                       operator: str = 'equals') -> 'XELAnalyzer':
+        """
+        Filter events by field value.
+
+        Args:
+            field_path: Field path (e.g., 'data.duration', 'actions.session_id')
+            value: Value to compare (None means field exists)
+            operator: Comparison operator (equals, contains, gt, lt, gte, lte, exists)
+
+        Returns:
+            New XELAnalyzer with filtered events
+        """
+        filtered = []
+        for event in self.events:
+            field_value = self._get_nested_value(event, field_path)
+
+            if operator == 'exists':
+                if field_value is not None:
+                    filtered.append(event)
+            elif operator == 'equals':
+                if field_value == value:
+                    filtered.append(event)
+            elif operator == 'contains':
+                if value and field_value and str(value).lower() in str(field_value).lower():
+                    filtered.append(event)
+            elif operator == 'gt':
+                try:
+                    if field_value is not None and field_value > value:
+                        filtered.append(event)
+                except TypeError:
+                    pass
+            elif operator == 'lt':
+                try:
+                    if field_value is not None and field_value < value:
+                        filtered.append(event)
+                except TypeError:
+                    pass
+            elif operator == 'gte':
+                try:
+                    if field_value is not None and field_value >= value:
+                        filtered.append(event)
+                except TypeError:
+                    pass
+            elif operator == 'lte':
+                try:
+                    if field_value is not None and field_value <= value:
+                        filtered.append(event)
+                except TypeError:
+                    pass
+
+        return XELAnalyzer(filtered)
+
+    def search(self, query: str, fields: Optional[List[str]] = None) -> 'XELAnalyzer':
+        """
+        Search for events containing query string.
+
+        Args:
+            query: Search query (regex supported)
+            fields: Specific fields to search (None = search all)
+
+        Returns:
+            New XELAnalyzer with matching events
+        """
+        try:
+            pattern = re.compile(query, re.IGNORECASE)
+        except re.error:
+            # If regex fails, use literal string
+            pattern = None
+
+        filtered = []
+        for event in self.events:
+            if self._search_in_dict(event, pattern or query, fields):
+                filtered.append(event)
+
+        return XELAnalyzer(filtered)
+
+    def group_by(self, field_path: str) -> Dict[str, List[Dict[str, Any]]]:
+        """
+        Group events by field value.
+
+        Args:
+            field_path: Field path to group by
+
+        Returns:
+            Dictionary mapping field values to event lists
+        """
+        groups = defaultdict(list)
+        for event in self.events:
+            value = self._get_nested_value(event, field_path)
+            key = str(value) if value is not None else 'null'
+            groups[key].append(event)
+
+        return dict(groups)
+
+    def aggregate(self, field_path: str, operation: str = 'count') -> Dict[str, Any]:
+        """
+        Aggregate events by field.
+
+        Args:
+            field_path: Field path to aggregate
+            operation: Aggregation operation (count, sum, avg, min, max, distinct)
+
+        Returns:
+            Aggregation results
+        """
+        values = []
+        for event in self.events:
+            value = self._get_nested_value(event, field_path)
+            if value is not None:
+                values.append(value)
+
+        if operation == 'count':
+            return {'count': len(self.events)}
+        elif operation == 'distinct':
+            return {'distinct_values': list(set(values)), 'distinct_count': len(set(values))}
+        elif not values:
+            return {'error': 'No values found'}
+
+        try:
+            if operation == 'sum':
+                return {'sum': sum(values)}
+            elif operation == 'avg':
+                return {'avg': sum(values) / len(values)}
+            elif operation == 'min':
+                return {'min': min(values)}
+            elif operation == 'max':
+                return {'max': max(values)}
+        except (TypeError, ValueError) as e:
+            return {'error': f'Cannot perform {operation} on non-numeric values'}
+
+        return {'error': f'Unknown operation: {operation}'}
+
+    def count_by(self, field_path: str) -> Dict[str, int]:
+        """
+        Count events by field value.
+
+        Args:
+            field_path: Field path to count by
+
+        Returns:
+            Dictionary mapping values to counts
+        """
+        counts = defaultdict(int)
+        for event in self.events:
+            value = self._get_nested_value(event, field_path)
+            key = str(value) if value is not None else 'null'
+            counts[key] += 1
+
+        return dict(sorted(counts.items(), key=lambda x: x[1], reverse=True))
+
+    def top_n(self, field_path: str, n: int = 10) -> List[tuple]:
+        """
+        Get top N values by frequency.
+
+        Args:
+            field_path: Field path to analyze
+            n: Number of top items to return
+
+        Returns:
+            List of (value, count) tuples
+        """
+        counts = self.count_by(field_path)
+        return sorted(counts.items(), key=lambda x: x[1], reverse=True)[:n]
+
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get statistical overview of events.
+
+        Returns:
+            Statistics dictionary
+        """
+        if not self.events:
+            return {'total_events': 0}
+
+        # Count by event type
+        event_types = self.count_by('name')
+
+        # Get time range
+        timestamps = [e.get('timestamp', '') for e in self.events if e.get('timestamp')]
+        time_range = None
+        if timestamps:
+            try:
+                timestamps.sort()
+                time_range = {'start': timestamps[0], 'end': timestamps[-1]}
+            except:
+                pass
+
+        # Get all fields
+        all_fields = set()
+        for event in self.events:
+            all_fields.update(event.keys())
+            if 'data' in event:
+                all_fields.update(f"data.{k}" for k in event['data'].keys())
+            if 'actions' in event:
+                all_fields.update(f"actions.{k}" for k in event['actions'].keys())
+
+        return {
+            'total_events': len(self.events),
+            'event_types': event_types,
+            'time_range': time_range,
+            'unique_fields': sorted(all_fields)
+        }
+
+    def custom_filter(self, predicate: Callable[[Dict[str, Any]], bool]) -> 'XELAnalyzer':
+        """
+        Filter events using custom predicate function.
+
+        Args:
+            predicate: Function that takes an event and returns True/False
+
+        Returns:
+            New XELAnalyzer with filtered events
+        """
+        filtered = [e for e in self.events if predicate(e)]
+        return XELAnalyzer(filtered)
+
+    def get_events(self) -> List[Dict[str, Any]]:
+        """
+        Get the current list of events.
+
+        Returns:
+            List of events
+        """
+        return self.events
+
+    # Helper methods
+
+    def _get_nested_value(self, d: Dict[str, Any], path: str) -> Any:
+        """Get value from nested dictionary using dot notation."""
+        keys = path.split('.')
+        value = d
+        for key in keys:
+            if isinstance(value, dict):
+                value = value.get(key)
+            else:
+                return None
+        return value
+
+    def _search_in_dict(self, d: Dict[str, Any], query: Any,
+                       fields: Optional[List[str]] = None,
+                       prefix: str = '') -> bool:
+        """Recursively search dictionary for query."""
+        for key, value in d.items():
+            current_path = f"{prefix}.{key}" if prefix else key
+
+            # Check if we should search this field
+            if fields and current_path not in fields:
+                if isinstance(value, dict):
+                    if self._search_in_dict(value, query, fields, current_path):
+                        return True
+                continue
+
+            # Search in value
+            if isinstance(value, dict):
+                if self._search_in_dict(value, query, fields, current_path):
+                    return True
+            elif value is not None:
+                value_str = str(value)
+                if isinstance(query, re.Pattern):
+                    if query.search(value_str):
+                        return True
+                else:
+                    if str(query).lower() in value_str.lower():
+                        return True
+
+        return False
+
+    def _parse_timestamp(self, timestamp: str) -> datetime:
+        """Parse timestamp string to datetime."""
+        # Try common formats
+        formats = [
+            '%Y-%m-%dT%H:%M:%S.%fZ',
+            '%Y-%m-%dT%H:%M:%SZ',
+            '%Y-%m-%d %H:%M:%S.%f',
+            '%Y-%m-%d %H:%M:%S',
+            '%Y-%m-%d',
+        ]
+
+        for fmt in formats:
+            try:
+                return datetime.strptime(timestamp, fmt)
+            except ValueError:
+                continue
+
+        # If all fail, try generic parsing
+        from dateutil import parser
+        return parser.parse(timestamp)