logler 1.1.2__cp311-cp311-win_amd64.whl → 1.1.3__cp311-cp311-win_amd64.whl

logler/cli.py

@@ -140,8 +140,11 @@ def stats(files: tuple, output_json: bool):
 @click.option("--patterns", is_flag=True, help="Find repeated patterns")
 @click.option("--thread", type=str, help="Follow specific thread ID")
 @click.option("--correlation", type=str, help="Follow specific correlation ID")
+@click.option("--trace", type=str, help="Follow specific trace ID")
 @click.option(
-    "--hierarchy", is_flag=True, help="Show thread hierarchy tree (with --thread or --correlation)"
+    "--hierarchy",
+    is_flag=True,
+    help="Show thread hierarchy tree (with --thread, --correlation, or --trace)",
 )
 @click.option("--waterfall", is_flag=True, help="Show waterfall timeline (with --hierarchy)")
 @click.option("--flamegraph", is_flag=True, help="Show flamegraph visualization (with --hierarchy)")
@@ -175,6 +178,7 @@ def investigate(
     patterns: bool,
     thread: Optional[str],
     correlation: Optional[str],
+    trace: Optional[str],
     hierarchy: bool,
     waterfall: bool,
     flamegraph: bool,
@@ -195,9 +199,10 @@ def investigate(
         logler investigate app.log --patterns          # Find repeated patterns
         logler investigate app.log --thread worker-1   # Follow specific thread
         logler investigate app.log --correlation req-123  # Follow request
-        logler investigate app.log --thread req-123 --hierarchy   # Show hierarchy tree
-        logler investigate app.log --thread req-123 --hierarchy --waterfall  # Show waterfall timeline
-        logler investigate app.log --thread req-123 --hierarchy --flamegraph  # Show flamegraph
+        logler investigate app.log --trace trace-abc123  # Follow distributed trace
+        logler investigate app.log --correlation req-123 --hierarchy   # Show hierarchy tree
+        logler investigate app.log --correlation req-123 --hierarchy --waterfall  # Show waterfall timeline
+        logler investigate app.log --correlation req-123 --hierarchy --flamegraph  # Show flamegraph
         logler investigate app.log --hierarchy --show-error-flow  # Analyze error propagation
         logler investigate app.log --output summary    # Token-efficient output
     """
@@ -217,8 +222,14 @@ def investigate(
 
     console = Console()
     file_list = list(files)
+    id_args = {"thread": thread, "correlation": correlation, "trace": trace}
+    provided_ids = [name for name, value in id_args.items() if value]
 
     try:
+        if len(provided_ids) > 1:
+            console.print("[red]❌ Provide only one of --thread, --correlation, or --trace.[/red]")
+            sys.exit(2)
+
         # Auto-insights mode (most powerful)
         if auto_insights:
             console.print("[bold cyan]🎯 Running automatic insights analysis...[/bold cyan]\n")
@@ -305,9 +316,9 @@ def investigate(
                 console.print("[yellow]No repeated patterns found.[/yellow]")
 
         # Thread/correlation following mode
-        elif thread or correlation:
-            identifier = thread or correlation
-            id_type = "thread" if thread else "correlation"
+        elif thread or correlation or trace:
+            identifier = thread or correlation or trace
+            id_type = "thread" if thread else "correlation" if correlation else "trace"
 
             # Hierarchy mode
             if hierarchy:
@@ -377,7 +388,7 @@ def investigate(
                 console.print(f"[bold cyan]🧵 Following {id_type}: {identifier}...[/bold cyan]\n")
 
                 result = follow_thread(
-                    files=file_list, thread_id=thread, correlation_id=correlation
+                    files=file_list, thread_id=thread, correlation_id=correlation, trace_id=trace
                 )
 
                 if output_json:

logler/investigate.py

@@ -464,7 +464,8 @@ def follow_thread_hierarchy(
                 "depth": 1
             },
             "error_nodes": ["worker-2.api-call"],
-            "detection_method": "ExplicitParentId" | "NamingPattern" | "TemporalInference" | "Mixed"
+            "detection_method": "ExplicitParentId" | "NamingPattern" | "TemporalInference" | "Mixed",
+            "detection_methods": ["ExplicitParentId", "NamingPattern"]
         }
 
     Example:
@@ -510,6 +511,16 @@ def follow_thread_hierarchy(
     return json.loads(result_json)
 
 
+def _format_detection_method(hierarchy: Dict[str, Any]) -> str:
+    method = hierarchy.get("detection_method", "Unknown")
+    methods = hierarchy.get("detection_methods") or []
+    method_str = str(method)
+    method_list = [str(m) for m in methods if m]
+    if method_list and (method_str == "Mixed" or len(method_list) > 1):
+        return f"{method_str} ({', '.join(method_list)})"
+    return method_str
+
+
 def get_hierarchy_summary(hierarchy: Dict[str, Any]) -> str:
     """
     Generate a human-readable summary of a thread hierarchy.
@@ -531,12 +542,12 @@ def get_hierarchy_summary(hierarchy: Dict[str, Any]) -> str:
     lines.append("=== Thread Hierarchy Summary ===")
     lines.append(f"Total nodes: {hierarchy.get('total_nodes', 0)}")
     lines.append(f"Max depth: {hierarchy.get('max_depth', 0)}")
-    lines.append(f"Detection method: {hierarchy.get('detection_method', 'Unknown')}")
+    lines.append(f"Detection method: {_format_detection_method(hierarchy)}")
 
     # Duration
     total_duration = hierarchy.get("total_duration_ms")
     if total_duration:
-        lines.append(f"Total duration: {total_duration}ms ({total_duration/1000:.2f}s)")
+        lines.append(f"Total duration: {total_duration}ms ({total_duration / 1000:.2f}s)")
 
     # Concurrent operations
     concurrent = hierarchy.get("concurrent_count", 0)
@@ -3167,7 +3178,7 @@ class InvestigationSession:
 
         for i, entry in enumerate(self.history):
             marker = "→" if i == self.current_index else " "
-            lines.append(f"  {marker} {i+1}. {entry['description']}")
+            lines.append(f"  {marker} {i + 1}. {entry['description']}")
             if entry.get("result_summary"):
                 for key, value in entry["result_summary"].items():
                     lines.append(f"      {key}: {value}")
@@ -3244,7 +3255,7 @@ class InvestigationSession:
             desc = entry["description"]
             operation = entry["operation"]
 
-            lines.append(f"### Step {i+1}: {desc}")
+            lines.append(f"### Step {i + 1}: {desc}")
             lines.append("")
             lines.append(f"- **Time:** {timestamp}")
             lines.append(f"- **Operation:** `{operation}`")
@@ -3294,7 +3305,7 @@ class InvestigationSession:
 
         for i, entry in enumerate(self.history):
             timestamp = entry.get("timestamp", "Unknown")
-            lines.append(f"{i+1}. [{timestamp}] {entry['description']}")
+            lines.append(f"{i + 1}. [{timestamp}] {entry['description']}")
 
             if entry.get("result_summary"):
                 for key, value in entry["result_summary"].items():
@@ -3685,7 +3696,9 @@ def analyze_with_insights(
                     "suggestion": "Investigate most common errors first",
                 }
             )
-            next_steps.append("Run: find_patterns(files, min_occurrences=3)")
+            next_steps.append(
+                'Run: logler llm sql "SELECT message, COUNT(*) FROM logs GROUP BY message ORDER BY COUNT(*) DESC" to find patterns'
+            )
 
     # Insight 2: Pattern detection
     if auto_investigate and error_count > 0:
@@ -3743,13 +3756,17 @@ def analyze_with_insights(
                     "suggestion": "Compare successful vs failed requests",
                 }
             )
-            next_steps.append("Use: compare_threads() to find differences")
+            next_steps.append(
+                "Run: logler llm compare <failed_id> <success_id> to find differences"
+            )
 
     # Generate suggestions based on insights
     if not suggestions:
         if error_count > 0:
             suggestions.append("Start by examining the first error - it may be the root cause")
-            suggestions.append("Use follow_thread() to see full request flow")
+            suggestions.append(
+                "Run: logler llm correlate <correlation_id> to see full request flow"
+            )
         else:
             suggestions.append("No errors found - logs look healthy")
 

logler/llm_cli.py

@@ -498,8 +498,8 @@ def sample(files: tuple, strategy: str, size: int, pretty: bool):
         if "level_distribution" in result:
             output["sample"]["coverage"] = {"levels": result["level_distribution"]}
 
-        # Transform entries
-        for entry in result.get("entries", []):
+        # Transform entries (key is 'samples' from Rust, not 'entries')
+        for entry in result.get("samples", []) or result.get("entries", []):
             out_entry = {
                 "line_number": entry.get("line_number"),
                 "timestamp": entry.get("timestamp"),
@@ -848,7 +848,7 @@ def verify_pattern(
                                 match_info["groups"] = list(match.groups())
                                 for j, grp in enumerate(match.groups()):
                                     if grp:
-                                        group_values[f"group_{j+1}"][grp] += 1
+                                        group_values[f"group_{j + 1}"][grp] += 1
 
                             matches.append(match_info)
 
@@ -1915,3 +1915,301 @@ def export_trace(identifier: str, files: tuple, export_format: str, pretty: bool
 
     except Exception as e:
         _error_json(f"Internal error: {str(e)}", EXIT_INTERNAL_ERROR)
+
+
+# =============================================================================
+# Compare Command - Compare two requests side by side
+# =============================================================================
+
+
+@llm.command()
+@click.argument("id1")
+@click.argument("id2")
+@click.option("--files", "-f", multiple=True, help="Files to search (supports globs)")
+@click.option("--pretty", is_flag=True, help="Pretty-print JSON output")
+def compare(id1: str, id2: str, files: tuple, pretty: bool):
+    """
+    Compare two requests/traces side by side.
+
+    Shows differences between a failed and successful request,
+    helping identify what went wrong.
+
+    Example:
+        logler llm compare req-001 req-003 --files "*.log"
+    """
+    from . import investigate
+
+    try:
+        file_list = _expand_globs(list(files)) if files else _expand_globs(["*.log"])
+        if not file_list:
+            _error_json(f"No files found matching: {files or ['*.log']}")
+
+        # Get timelines for both requests
+        result1 = investigate.follow_thread(file_list, correlation_id=id1)
+        result2 = investigate.follow_thread(file_list, correlation_id=id2)
+
+        entries1 = result1.get("entries", [])
+        entries2 = result2.get("entries", [])
+
+        # Analyze each request
+        def analyze_request(entries: List[Dict[str, Any]], req_id: str) -> Dict[str, Any]:
+            if not entries:
+                return {"id": req_id, "found": False}
+
+            levels = defaultdict(int)
+            messages = []
+            timestamps = []
+            errors = []
+
+            for e in entries:
+                level = e.get("level", "UNKNOWN")
+                levels[level] += 1
+                messages.append(e.get("message", ""))
+                if e.get("timestamp"):
+                    timestamps.append(e["timestamp"])
+                if level in ["ERROR", "FATAL", "CRITICAL"]:
+                    errors.append(
+                        {
+                            "message": e.get("message"),
+                            "timestamp": e.get("timestamp"),
+                            "line_number": e.get("line_number"),
+                        }
+                    )
+
+            # Calculate duration
+            duration_ms = None
+            if len(timestamps) >= 2:
+                try:
+                    start = datetime.fromisoformat(timestamps[0].replace("Z", "+00:00"))
+                    end = datetime.fromisoformat(timestamps[-1].replace("Z", "+00:00"))
+                    duration_ms = int((end - start).total_seconds() * 1000)
+                except (ValueError, TypeError):
+                    pass
+
+            return {
+                "id": req_id,
+                "found": True,
+                "entry_count": len(entries),
+                "duration_ms": duration_ms,
+                "outcome": "error" if errors else "success",
+                "levels": dict(levels),
+                "errors": errors,
+                "steps": [e.get("message", "")[:80] for e in entries],
+            }
+
+        analysis1 = analyze_request(entries1, id1)
+        analysis2 = analyze_request(entries2, id2)
+
+        # Find differences
+        differences = []
+
+        if analysis1["found"] and analysis2["found"]:
+            # Duration difference
+            if analysis1.get("duration_ms") and analysis2.get("duration_ms"):
+                diff_ms = analysis1["duration_ms"] - analysis2["duration_ms"]
+                if abs(diff_ms) > 100:  # Significant difference
+                    differences.append(
+                        {
+                            "type": "duration",
+                            "description": f"{id1} took {diff_ms:+d}ms compared to {id2}",
+                            "value1": analysis1["duration_ms"],
+                            "value2": analysis2["duration_ms"],
+                        }
+                    )
+
+            # Entry count difference
+            if analysis1["entry_count"] != analysis2["entry_count"]:
+                differences.append(
+                    {
+                        "type": "entry_count",
+                        "description": f"{id1} has {analysis1['entry_count']} entries, {id2} has {analysis2['entry_count']}",
+                        "value1": analysis1["entry_count"],
+                        "value2": analysis2["entry_count"],
+                    }
+                )
+
+            # Outcome difference
+            if analysis1["outcome"] != analysis2["outcome"]:
+                differences.append(
+                    {
+                        "type": "outcome",
+                        "description": f"{id1} {analysis1['outcome']}, {id2} {analysis2['outcome']}",
+                        "value1": analysis1["outcome"],
+                        "value2": analysis2["outcome"],
+                    }
+                )
+
+            # Find where they diverge
+            steps1 = analysis1.get("steps", [])
+            steps2 = analysis2.get("steps", [])
+            divergence_point = None
+            for i, (s1, s2) in enumerate(zip(steps1, steps2)):
+                if s1 != s2:
+                    divergence_point = {
+                        "step": i + 1,
+                        "request1": s1,
+                        "request2": s2,
+                    }
+                    break
+
+            if divergence_point:
+                differences.append(
+                    {
+                        "type": "divergence",
+                        "description": f"Requests diverge at step {divergence_point['step']}",
+                        "detail": divergence_point,
+                    }
+                )
+
+        output = {
+            "comparison": {
+                "request1": analysis1,
+                "request2": analysis2,
+            },
+            "differences": differences,
+            "summary": f"{id1}: {analysis1.get('outcome', 'not found')}, {id2}: {analysis2.get('outcome', 'not found')}",
+        }
+
+        # Add recommendation if one failed and one succeeded
+        if analysis1.get("outcome") == "error" and analysis2.get("outcome") == "success":
+            if analysis1.get("errors"):
+                output["recommendation"] = (
+                    f"Investigate error in {id1}: {analysis1['errors'][0].get('message', 'Unknown error')}"
+                )
+        elif analysis2.get("outcome") == "error" and analysis1.get("outcome") == "success":
+            if analysis2.get("errors"):
+                output["recommendation"] = (
+                    f"Investigate error in {id2}: {analysis2['errors'][0].get('message', 'Unknown error')}"
+                )
+
+        _output_json(output, pretty)
+        sys.exit(EXIT_SUCCESS)
+
+    except Exception as e:
+        _error_json(f"Internal error: {str(e)}", EXIT_INTERNAL_ERROR)
+
+
+# =============================================================================
+# Summarize Command - Quick text summary for LLMs
+# =============================================================================
+
+
+@llm.command()
+@click.argument("files", nargs=-1, required=True)
+@click.option(
+    "--focus",
+    type=click.Choice(["errors", "all", "warnings"]),
+    default="errors",
+    help="What to focus on",
+)
+@click.option("--pretty", is_flag=True, help="Pretty-print JSON output")
+def summarize(files: tuple, focus: str, pretty: bool):
+    """
+    Generate a concise summary of log contents.
+
+    Returns structured data with a human-readable summary,
+    perfect for LLM context.
+
+    Example:
+        logler llm summarize app.log --focus errors
+    """
+    from .parser import LogParser
+
+    try:
+        file_list = _expand_globs(list(files))
+        if not file_list:
+            _error_json(f"No files found matching: {files}")
+
+        parser = LogParser()
+
+        # Collect stats
+        total = 0
+        by_level = defaultdict(int)
+        errors = []
+        warnings = []
+        unique_errors = defaultdict(int)
+        time_range = {"start": None, "end": None}
+        correlation_ids = set()
+
+        for file_path in file_list:
+            try:
+                with open(file_path, "r", errors="replace") as f:
+                    for i, line in enumerate(f):
+                        line = line.rstrip()
+                        if not line:
+                            continue
+
+                        entry = parser.parse_line(i + 1, line)
+                        total += 1
+
+                        level = str(entry.level).upper() if entry.level else "UNKNOWN"
+                        by_level[level] += 1
+
+                        if entry.timestamp:
+                            ts_str = str(entry.timestamp)
+                            if not time_range["start"] or ts_str < time_range["start"]:
+                                time_range["start"] = ts_str
+                            if not time_range["end"] or ts_str > time_range["end"]:
+                                time_range["end"] = ts_str
+
+                        if entry.correlation_id:
+                            correlation_ids.add(entry.correlation_id)
+
+                        if level == "ERROR":
+                            msg = entry.message or line[:100]
+                            unique_errors[msg] += 1
+                            if len(errors) < 10:
+                                errors.append(
+                                    {
+                                        "line": i + 1,
+                                        "message": msg,
+                                        "correlation_id": entry.correlation_id,
+                                    }
+                                )
+                        elif level in ["WARN", "WARNING"]:
+                            if len(warnings) < 5:
+                                warnings.append(
+                                    {
+                                        "line": i + 1,
+                                        "message": entry.message or line[:100],
+                                    }
+                                )
+
+            except (FileNotFoundError, PermissionError):
+                pass
+
+        # Build human-readable summary
+        error_count = by_level.get("ERROR", 0)
+        warn_count = by_level.get("WARN", 0) + by_level.get("WARNING", 0)
+
+        if error_count == 0 and warn_count == 0:
+            summary_text = f"Clean: {total} log entries, no errors or warnings"
+        elif error_count == 0:
+            summary_text = f"{total} entries with {warn_count} warnings, no errors"
+        else:
+            error_types = len(unique_errors)
+            summary_text = f"{total} entries, {error_count} errors ({error_types} unique), {warn_count} warnings"
+
+            # Add top error
+            if unique_errors:
+                top_error = max(unique_errors.items(), key=lambda x: x[1])
+                summary_text += f'. Top error: "{top_error[0][:50]}" ({top_error[1]}x)'
+
+        output = {
+            "summary": summary_text,
+            "stats": {
+                "total_entries": total,
+                "by_level": dict(by_level),
+                "unique_correlation_ids": len(correlation_ids),
+                "time_range": time_range if time_range["start"] else None,
+            },
+            "errors": errors if focus in ["errors", "all"] else [],
+            "warnings": warnings if focus in ["warnings", "all"] else [],
+            "unique_error_messages": dict(unique_errors) if unique_errors else {},
+        }
+
+        _output_json(output, pretty)
+        sys.exit(EXIT_SUCCESS if total > 0 else EXIT_NO_RESULTS)
+
+    except Exception as e:
+        _error_json(f"Internal error: {str(e)}", EXIT_INTERNAL_ERROR)

logler/models.py

@@ -66,6 +66,7 @@ class DetectionMethod(str, Enum):
     EXPLICIT_PARENT_ID = "ExplicitParentId"
     NAMING_PATTERN = "NamingPattern"
     TEMPORAL_INFERENCE = "TemporalInference"
+    CORRELATION_CHAIN = "CorrelationChain"
     MIXED = "Mixed"
     UNKNOWN = "Unknown"
 
@@ -235,6 +236,9 @@ class ThreadHierarchy(BaseModel):
     bottleneck: Optional[BottleneckInfo] = Field(None, description="Performance bottleneck")
     error_nodes: List[str] = Field(default_factory=list, description="Node IDs with errors")
     detection_method: str = Field("Unknown", description="How relationships were detected")
+    detection_methods: List[str] = Field(
+        default_factory=list, description="Detection methods used (detailed)"
+    )
 
 
 # =============================================================================

logler/parser.py

@@ -38,6 +38,7 @@ class LogEntry:
     trace_id: Optional[str] = None
     span_id: Optional[str] = None
     service_name: Optional[str] = None
+    format: Optional[str] = None
     fields: Dict[str, Any] = field(default_factory=dict)
 
     def __post_init__(self):
@@ -82,6 +83,7 @@ class LogParser:
     def _parse_json(self, line_number: int, raw: str, data: dict) -> LogEntry:
         """Parse JSON log entry."""
         entry = LogEntry(line_number=line_number, raw=raw)
+        entry.format = "Json"
 
         # Extract timestamp
         for ts_field in ["timestamp", "time", "ts", "@timestamp", "datetime"]:
@@ -167,6 +169,7 @@ class LogParser:
     def _parse_plain(self, line_number: int, raw: str) -> LogEntry:
         """Parse plain text log entry."""
         entry = LogEntry(line_number=line_number, raw=raw, message=raw)
+        entry.format = "PlainText"
 
         # Extract timestamp
         ts_match = self.PATTERNS["timestamp"].search(raw)

logler/tree_formatter.py

@@ -63,6 +63,27 @@ def format_tree(
         )
 
 
+def _format_detection_method(hierarchy: Dict[str, Any]) -> str:
+    method = hierarchy.get("detection_method", "Unknown")
+    methods = hierarchy.get("detection_methods") or []
+    method_str = str(method)
+    method_list = [str(m) for m in methods if m]
+    if method_list and (method_str == "Mixed" or len(method_list) > 1):
+        return f"{method_str} ({', '.join(method_list)})"
+    return method_str
+
+
+def _timeline_label(hierarchy: Dict[str, Any]) -> str:
+    roots = hierarchy.get("roots", [])
+    if not roots:
+        return "Hierarchy"
+    root = roots[0]
+    label = root.get("name") or root.get("operation_name") or root.get("id", "root")
+    if len(roots) > 1:
+        label = f"{label} (+{len(roots) - 1} more)"
+    return label
+
+
 def _format_ascii_tree(
     hierarchy: Dict[str, Any],
     mode: str,
@@ -80,7 +101,7 @@ def _format_ascii_tree(
     lines.append("=" * 70)
     lines.append(f"Total nodes: {hierarchy.get('total_nodes', 0)}")
     lines.append(f"Max depth: {hierarchy.get('max_depth', 0)}")
-    lines.append(f"Detection: {hierarchy.get('detection_method', 'Unknown')}")
+    lines.append(f"Detection: {_format_detection_method(hierarchy)}")
 
     total_duration = hierarchy.get("total_duration_ms")
     if total_duration and show_duration:
@@ -412,7 +433,7 @@ def _format_duration(ms: Optional[int]) -> str:
     if ms < 1000:
         return f"{ms}ms"
     elif ms < 60000:
-        return f"{ms/1000:.2f}s"
+        return f"{ms / 1000:.2f}s"
     else:
         minutes = ms // 60000
         seconds = (ms % 60000) / 1000
@@ -495,10 +516,10 @@ def format_waterfall(
 
     # Header
     lines.append("┌" + "─" * (effective_width - 2) + "┐")
-    header = f"Timeline: {hierarchy.get('detection_method', 'Hierarchy')} ({_format_duration(total_duration)})"
+    header = f"Timeline: {_timeline_label(hierarchy)} ({_format_duration(total_duration)})"
     if len(header) > effective_width - 4:
         header = header[: effective_width - 7] + "..."
-    lines.append(f"│ {header:<{effective_width-4}} │")
+    lines.append(f"│ {header:<{effective_width - 4}} │")
     lines.append("├" + "─" * (effective_width - 2) + "┤")
 
     # Collect all nodes in order
@@ -702,7 +723,7 @@ def format_flamegraph(
             return "<1ms"  # Show marker for 0ms durations
         if ms < 1000:
             return f"{ms:.0f}ms"
-        return f"{ms/1000:.2f}s"
+        return f"{ms / 1000:.2f}s"
 
     # Build layers by depth
     max_depth = hierarchy.get("max_depth", 0)

{logler-1.1.2.dist-info → logler-1.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logler
-Version: 1.1.2
+Version: 1.1.3
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -92,75 +92,116 @@ A modern, feature-rich log viewer that makes debugging a pleasure. View logs in
 - 🤔 **Explain Feature** - Plain English explanations of cryptic errors with next steps
 - 💬 **Contextual Suggestions** - AI suggests what to investigate next based on findings
 
+### Public API Contract
+
+Each code block carries a **Contract ID** (e.g., `[C01]`). The test suite in `tests/test_readme.py` executes these snippets against the documented public APIs. When this section changes, the tests must change with it — CI proves the README.
+
+#### [C01] Auto-insights analysis
 ```python
 import logler.investigate as investigate
 
-# 🎯 One-line auto investigation with insights
 result = investigate.analyze_with_insights(files=["app.log"])
 print(result['insights'])  # Automatic pattern detection, error analysis, suggestions
+```
+
+#### [C02] Token-efficient search
+```python
+import logler.investigate as investigate
 
-# 📉 Token-efficient search (44x smaller output)
 errors = investigate.search(files=["app.log"], level="ERROR", output_format="summary")
 # Returns aggregated stats instead of all entries - perfect for limited context windows
+```
+
+#### [C03] Compare threads
+```python
+import logler.investigate as investigate
 
-# 🔀 Compare successful vs failed requests
 diff = investigate.compare_threads(
     files=["app.log"],
     correlation_a="req-success-123",
     correlation_b="req-failed-456"
 )
-print(diff['summary'])  # "Thread B took 2341ms longer and had 5 errors (cache miss, timeout)"
+print(diff['summary'])  # Comparison of two request flows
+```
+
+#### [C04] Cross-service timeline
+```python
+import logler.investigate as investigate
 
-# 🌐 Cross-service distributed tracing
 timeline = investigate.cross_service_timeline(
     files={"api": ["api.log"], "db": ["db.log"], "cache": ["cache.log"]},
     correlation_id="req-12345"
 )
 # See request flow: API → DB → Cache with latency breakdown
+```
+
+#### [C05] Investigation sessions
+```python
+import logler.investigate as investigate
 
-# 📝 Track investigation with sessions
 session = investigate.InvestigationSession(files=["app.log"], name="incident_2024")
 session.search(level="ERROR")
 session.find_patterns()
 session.add_note("Database connection pool exhausted")
 report = session.generate_report(format="markdown")  # Auto-generate report
+```
+
+#### [C06] Smart sampling
+```python
+import logler.investigate as investigate
 
-# 🎯 Smart sampling (representative sample of huge logs)
 sample = investigate.smart_sample(
     files=["huge.log"],
     strategy="errors_focused",  # or "diverse", "representative", "chronological"
     sample_size=50
 )
+```
+
+#### [C07] Error explanation
+```python
+import logler.investigate as investigate
 
-# 🤔 Explain cryptic errors in plain English
 explanation = investigate.explain(error_message="Connection pool exhausted", context="production")
 print(explanation)  # Common causes, next steps, production-specific advice
+```
+
+#### [C08] Thread hierarchy
+```python
+import logler.investigate as investigate
 
-# 🌳 Hierarchical thread visualization (NEW!)
 hierarchy = investigate.follow_thread_hierarchy(
     files=["app.log"],
     root_identifier="req-123",
     min_confidence=0.8  # Only show high-confidence relationships
 )
-
 # Automatic bottleneck detection
-if hierarchy['bottleneck']:
+if hierarchy.get('bottleneck'):
     print(f"Bottleneck: {hierarchy['bottleneck']['node_id']} took {hierarchy['bottleneck']['duration_ms']}ms")
+```
+
+#### [C09] Hierarchy summary
+```python
+import logler.investigate as investigate
 
-# Get summary
+# Using hierarchy from [C08]
 summary = investigate.get_hierarchy_summary(hierarchy)
 print(summary)  # Shows tree structure, errors, bottlenecks
+```
 
-# Visualize in CLI
+#### [C10] Tree visualization
+```python
 from logler.tree_formatter import print_tree, print_waterfall
+
+# Using hierarchy from [C08]
 print_tree(hierarchy, mode="detailed", show_duration=True)
-print_waterfall(hierarchy, width=100)  # Waterfall timeline showing parallel operations
+print_waterfall(hierarchy, width=100)  # Waterfall timeline
 ```
 
 **📚 Complete LLM documentation:**
-- [English Guide](docs/LLM_README.md) - Complete API and examples
+- [LLM CLI Reference](docs/LLM_CLI_REFERENCE.md) - All 16 CLI commands for AI agents
+- [Python API Guide](docs/LLM_README.md) - Library API and examples
+- [API Reference](docs/LLM_INVESTIGATION_API.md) - All investigation functions
 - [日本語ガイド](README.ja.md) - 完全なドキュメント
-- [API Reference](docs/LLM_INVESTIGATION_API.md) - All investigation tools
 - [Examples](examples/) - Production incident investigations
 
 ## 🚀 Quick Start
@@ -200,16 +241,48 @@ logler investigate app.log --errors               # Analyze errors
 logler investigate app.log --patterns             # Find repeated patterns
 logler investigate app.log --thread worker-1      # Follow specific thread
 logler investigate app.log --correlation req-123  # Follow correlation ID
+logler investigate app.log --trace trace-abc123   # Follow distributed trace
 logler investigate app.log --output summary       # Token-efficient output
 
 # 🌳 NEW: Hierarchical Thread Visualization
 logler investigate app.log --correlation req-123 --hierarchy         # Show thread hierarchy tree
-logler investigate app.log --correlation trace-abc123 --hierarchy --waterfall  # Show waterfall timeline
+logler investigate app.log --trace trace-abc123 --hierarchy --waterfall        # Show waterfall timeline
 logler investigate app.log --correlation req-123 --hierarchy --flamegraph # Show flamegraph view
 logler investigate app.log --hierarchy --show-error-flow             # Analyze error propagation
 logler investigate app.log --thread worker-1 --hierarchy --max-depth 3   # Limit hierarchy depth
 ```
 
+**LLM-first CLI (JSON output by default):**
+
+Designed for AI agents - 16 commands with structured JSON output, no truncation.
+
+```bash
+# Assessment & Overview
+logler llm triage app.log --last 1h      # Quick severity assessment
+logler llm summarize app.log             # Concise summary with stats
+logler llm schema app.log                # Infer log structure
+
+# Search & Analysis
+logler llm search app.log --level ERROR  # Find entries (full results)
+logler llm sql "SELECT level, COUNT(*) FROM logs GROUP BY level" -f app.log
+
+# Request Tracing
+logler llm correlate req-123 --files "*.log"   # Follow correlation ID
+logler llm hierarchy trace-xyz --files "*.log"  # Build hierarchy tree
+logler llm bottleneck trace-xyz --files "*.log" # Find slow operations
+
+# Comparison
+logler llm compare req-fail req-success --files "*.log"  # Compare requests
+logler llm diff app.log --baseline 1h                    # Before/after analysis
+
+# Utilities
+logler llm sample app.log --strategy errors_focused --size 50
+logler llm context app.log 1523 --before 10 --after 10
+logler llm export trace-xyz --format jaeger
+```
+
+See **[LLM CLI Reference](docs/LLM_CLI_REFERENCE.md)** for complete documentation of all 16 commands.
+
 ### Visualization Modes
 
 **Tree View** - Shows parent-child relationships:
@@ -327,6 +400,7 @@ logler investigate app.log --patterns --min-occurrences 5
 # Follow a specific thread or request
 logler investigate app.log --thread worker-1
 logler investigate app.log --correlation req-abc123
+logler investigate app.log --trace trace-xyz789
 
 # Token-efficient output for LLMs
 logler investigate app.log --auto-insights --output summary
@@ -437,6 +511,9 @@ Track requests across services:
 # Follow a specific correlation ID
 logler investigate app.log --correlation req-12345
 
+# Follow a distributed trace ID
+logler investigate app.log --trace trace-xyz789
+
 # View across multiple service logs
 logler view app.log service.log --grep "req-12345"
 ```

{logler-1.1.2.dist-info → logler-1.1.3.dist-info}/RECORD

@@ -1,23 +1,23 @@
 logler\__init__.py,sha256=2BjL1FRLAqnHMa_3UMhmf6KQLnxkTbeUgTQQrBeZRuU,2921
 logler\bootstrap.py,sha256=4jWhVxy9Rq_PB1-3daVvo9_pS6QkimUmjLRYDfeMuA8,1276
 logler\cache.py,sha256=U5lstFY3FEA11pRHMk5UDlG5hIdLJwKszwVfWTprH4c,2399
-logler\cli.py,sha256=GiucDDgKBzA6qxdo67Eud2-9JyafEdJ7e1hBGtKb3So,21349
+logler\cli.py,sha256=_Vp-2YN1IDocCi76RP2vDVijaKAhM8B8prSwsq-_moc,21941
 logler\helpers.py,sha256=YYcXgPuW3aZs7Ty3y-U6xBQjo_zSivnOht3lwElHkt0,9464
-logler\investigate.py,sha256=zUs7lYeMmLT1ZfQwiQzLVhTIXogarrcQkIvjvzWCQyU,141853
-logler\llm_cli.py,sha256=L-RIp3vgAweloJ2VkhI609DdRh9d9dk6YoFRqSj-9Cs,68654
+logler\investigate.py,sha256=MlmI6wq87VsiBe27ri7xb2LBbrxbNmGEM8Xvlr4BL7E,142558
+logler\llm_cli.py,sha256=xk1bd4YZqCbC0J312PZBgpN8S-r3fQgRAs4FSwhAlgQ,80635
 logler\log_reader.py,sha256=d6vNx-2ZLc6XhbLDgH5nh84j6kZzTMElzZg80fL63Vo,8812
-logler\models.py,sha256=ET_wzQulZwRl5HxWNyqNrTFUBVwJEzfypv1YrXI4r8o,22258
-logler\parser.py,sha256=DmR4phqGVQXlb2vjZK6712jRN5gFVH1W3ABYVaufznQ,6691
+logler\models.py,sha256=UyF5apCtl1oUOFyEEN2_ORRgvd_1zpTbl7jQjEhh2Hw,22431
+logler\parser.py,sha256=sRpnTRClNi2ddPi0W20v4-KK5Alu4ZSkZyzp7dtGkIU,6792
 logler\safe_regex.py,sha256=7XREjaW74oCA9ocBFg-lAxu90aOM0CtArDnR9e1vOkY,3555
 logler\sql.py,sha256=nRwqqknSFpYhFGsjo_uVBG2Mg_Ez2jNj0UKxuJPF85Y,4996
 logler\terminal.py,sha256=kLZpa_VXKknWg2b-yK8-un2MZgeYj6DwNpdVrX2s5O0,8355
 logler\tracker.py,sha256=hI24eEBOyoGzQdDy9nyZQ04u7LX541UdTjcrzRoHXfw,4794
-logler\tree_formatter.py,sha256=57JdyD5BwKbiebz6xa53to6QMYxIJ11jE_SlJa2HPqY,29140
+logler\tree_formatter.py,sha256=t9SiRhLb7_9XZRwr3aU0SnYVuoNTu9YgUzvlRDB0Rl8,29885
 logler\watcher.py,sha256=yjacGh6ffqf7uoXuiR6HXR6uAP5RRof6gc7TLV-j5J0,1581
-logler-1.1.2.dist-info\METADATA,sha256=gwXRnvrzNLgynJUgI4ByFH1MkB93nCGBtWef62yFZDE,20910
-logler-1.1.2.dist-info\WHEEL,sha256=X79LywvMB9iCuFHu88xBAFTJDhRqJi6Yh9hhoCI9jao,97
-logler-1.1.2.dist-info\entry_points.txt,sha256=KAtycgnrhm85NgD_TCx2QslE9oClYHWKPM9NG598RNs,41
-logler-1.1.2.dist-info\licenses\LICENSE,sha256=rvAbCW736CB0UFBLmJ3Jz1vxrtFwCXv4F1OKNcDdY1s,1082
+logler-1.1.3.dist-info\METADATA,sha256=LGvA84NvVM48cBvfK0UAMCXU56pA5At8a0srggcn7hA,23117
+logler-1.1.3.dist-info\WHEEL,sha256=X79LywvMB9iCuFHu88xBAFTJDhRqJi6Yh9hhoCI9jao,97
+logler-1.1.3.dist-info\entry_points.txt,sha256=KAtycgnrhm85NgD_TCx2QslE9oClYHWKPM9NG598RNs,41
+logler-1.1.3.dist-info\licenses\LICENSE,sha256=rvAbCW736CB0UFBLmJ3Jz1vxrtFwCXv4F1OKNcDdY1s,1082
 logler_rs\__init__.py,sha256=y2ULUqMIhS92vwz6utTdkCn5l_T1Kso3YLGqCIZUxKY,119
-logler_rs\logler_rs.cp311-win_amd64.pyd,sha256=euHBNEEhDf-eu0XCmSOk7CYxoukZS4DHodZ6CUVJu94,2801664
-logler-1.1.2.dist-info\RECORD,,
+logler_rs\logler_rs.cp311-win_amd64.pyd,sha256=9sMC6nZc52IJzZlCiI4F0YNXB6G0zVQg-t6k2S82y4M,2770944
+logler-1.1.3.dist-info\RECORD,,