mdbkit 0.1.0__py3-none-any.whl

mdbkit/analysis.py

@@ -0,0 +1,436 @@
+"""Aggregation of parsed log entries into DBA-useful summaries.
+
+Three analyses, mirroring the most-used mtools workflows:
+
+* summarize      -> `mdbkit loginfo`  (like mloginfo)
+* QueryAggregator -> `mdbkit queries` (like mloginfo --queries)
+* ConnectionAggregator -> `mdbkit connections` (like mloginfo --connections)
+"""
+
+from __future__ import annotations
+
+import math
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from .parser import (
+    ID_BUILD_INFO,
+    ID_CLIENT_METADATA,
+    ID_CONN_ACCEPTED,
+    ID_CONN_ENDED,
+    ID_STARTUP,
+    LogEntry,
+)
+
+# ---------------------------------------------------------------------------
+# Query shape extraction
+# ---------------------------------------------------------------------------
+
+# Operators that keep equality semantics for index purposes.
+EQUALITY_OPS = {"$eq", "$in"}
+RANGE_OPS = {"$gt", "$gte", "$lt", "$lte"}
+LOW_SELECTIVITY_OPS = {"$ne", "$nin", "$exists", "$not"}
+SPECIAL_OPS = {"$text", "$where", "$expr", "$geoWithin", "$geoIntersects", "$near", "$nearSphere"}
+
+
+@dataclass(frozen=True)
+class QueryShape:
+    """A literal-free signature of a query: what fields, which operators, what sort."""
+
+    ns: str
+    operation: str
+    filter_fields: Tuple[Tuple[str, Tuple[str, ...]], ...]  # ((path, (ops...)), ...)
+    sort_fields: Tuple[Tuple[str, int], ...]  # ((path, direction), ...)
+    flags: Tuple[str, ...] = ()  # e.g. ("$or", "$text")
+
+    def pretty(self) -> str:
+        parts = []
+        for path, ops in self.filter_fields:
+            parts.append(f"{path}:{'|'.join(o.lstrip('$') for o in ops)}")
+        text = "{" + ", ".join(parts) + "}"
+        if self.sort_fields:
+            text += " sort:{" + ", ".join(f"{p}:{d}" for p, d in self.sort_fields) + "}"
+        if self.flags:
+            text += " [" + ",".join(self.flags) + "]"
+        return text
+
+
+def _walk_filter(node, prefix: str, out: Dict[str, set], flags: set, depth: int = 0):
+    """Recursively collect (field path -> operator set) from a filter document."""
+    if depth > 12 or not isinstance(node, dict):
+        return
+    for key, value in node.items():
+        if key in ("$and",):
+            if isinstance(value, list):
+                for sub in value:
+                    _walk_filter(sub, prefix, out, flags, depth + 1)
+        elif key in ("$or", "$nor"):
+            flags.add(key)
+            if isinstance(value, list):
+                for sub in value:
+                    _walk_filter(sub, prefix, out, flags, depth + 1)
+        elif key in SPECIAL_OPS:
+            flags.add(key)
+        elif key.startswith("$"):
+            # An operator appearing at document level we don't model; note it.
+            flags.add(key)
+        else:
+            path = f"{prefix}.{key}" if prefix else key
+            if isinstance(value, dict):
+                ops = {op for op in value.keys() if op.startswith("$")}
+                if ops:
+                    out[path].update(ops)
+                    inner = value.get("$elemMatch")
+                    if isinstance(inner, dict):
+                        _walk_filter(inner, path, out, flags, depth + 1)
+                    if "$regex" in ops:
+                        flags.add("$regex")
+                else:
+                    # Sub-document equality match on the whole object.
+                    out[path].add("$eq")
+            else:
+                out[path].add("$eq")
+
+
+def extract_shape(entry: LogEntry) -> Optional[QueryShape]:
+    """Build a QueryShape from a 'Slow query' log entry, or None if not applicable."""
+    attr = entry.attr
+    command = attr.get("command") if isinstance(attr.get("command"), dict) else {}
+    op_type = attr.get("type", "")
+
+    ns = attr.get("ns", "")
+    if (not ns or ns.endswith(".$cmd") or ns.endswith(".")) and command:
+        coll = (command.get("find") or command.get("aggregate")
+                or command.get("update") or command.get("delete")
+                or command.get("insert") or command.get("findAndModify")
+                or command.get("count") or command.get("distinct") or "")
+        db = command.get("$db", "")
+        if db and coll:
+            ns = f"{db}.{coll}"
+
+    filter_doc: dict = {}
+    sort_doc: dict = {}
+    operation = "unknown"
+
+    if "find" in command:
+        operation = "find"
+        filter_doc = command.get("filter") or {}
+        sort_doc = command.get("sort") or {}
+    elif "aggregate" in command:
+        operation = "aggregate"
+        pipeline = command.get("pipeline") or []
+        for stage in pipeline:
+            if not isinstance(stage, dict):
+                continue
+            if "$match" in stage and not filter_doc:
+                filter_doc = stage["$match"] or {}
+            elif "$sort" in stage and not sort_doc:
+                sort_doc = stage["$sort"] or {}
+            elif filter_doc or sort_doc:
+                break  # only leading $match/$sort benefit from an index
+    elif "count" in command:
+        operation = "count"
+        filter_doc = command.get("query") or {}
+    elif "distinct" in command:
+        operation = "distinct"
+        filter_doc = command.get("query") or {}
+    elif "getMore" in command:
+        origin = command.get("originatingCommand")
+        if isinstance(origin, dict):
+            fake = LogEntry(
+                ts=entry.ts, severity=entry.severity, component=entry.component,
+                msg_id=entry.msg_id, ctx=entry.ctx, msg=entry.msg,
+                attr={"ns": ns, "command": origin},
+            )
+            shape = extract_shape(fake)
+            if shape:
+                return QueryShape(shape.ns, "getMore(" + shape.operation + ")",
+                                  shape.filter_fields, shape.sort_fields, shape.flags)
+        operation = "getMore"
+    elif "update" in command and isinstance(command.get("updates"), list):
+        operation = "update"
+        first = command["updates"][0] if command["updates"] else {}
+        if isinstance(first, dict):
+            filter_doc = first.get("q") or {}
+    elif "delete" in command and isinstance(command.get("deletes"), list):
+        operation = "delete"
+        first = command["deletes"][0] if command["deletes"] else {}
+        if isinstance(first, dict):
+            filter_doc = first.get("q") or {}
+    elif op_type in ("update", "remove"):
+        operation = op_type
+        filter_doc = command.get("q") or {}
+    elif "findAndModify" in command:
+        operation = "findAndModify"
+        filter_doc = command.get("query") or {}
+        sort_doc = command.get("sort") or {}
+    elif "insert" in command or op_type == "insert":
+        operation = "insert"
+    elif command:
+        operation = next(iter(command.keys()), "unknown")
+
+    fields: Dict[str, set] = defaultdict(set)
+    flags: set = set()
+    _walk_filter(filter_doc, "", fields, flags)
+
+    filter_fields = tuple(sorted((p, tuple(sorted(ops))) for p, ops in fields.items()))
+    sort_fields = tuple(
+        (k, int(v) if isinstance(v, (int, float)) else 1) for k, v in sort_doc.items()
+    ) if isinstance(sort_doc, dict) else ()
+
+    return QueryShape(ns=ns, operation=operation, filter_fields=filter_fields,
+                      sort_fields=sort_fields, flags=tuple(sorted(flags)))
+
+
+# ---------------------------------------------------------------------------
+# Slow query aggregation
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ShapeStats:
+    shape: QueryShape
+    count: int = 0
+    durations: List[int] = field(default_factory=list)
+    docs_examined: int = 0
+    keys_examined: int = 0
+    n_returned: int = 0
+    collscan: bool = False
+    in_memory_sort: bool = False
+    plan_summaries: Counter = field(default_factory=Counter)
+    example: str = ""
+
+    def add(self, entry: LogEntry):
+        attr = entry.attr
+        self.count += 1
+        self.durations.append(int(attr.get("durationMillis", 0) or 0))
+        self.docs_examined += int(attr.get("docsExamined", 0) or 0)
+        self.keys_examined += int(attr.get("keysExamined", 0) or 0)
+        n = attr.get("nreturned")
+        if n is None:
+            n = attr.get("nMatched")
+        if n is None:
+            n = attr.get("ndeleted", attr.get("nDeleted"))
+        self.n_returned += int(n or 0)
+        plan = attr.get("planSummary", "")
+        if plan:
+            self.plan_summaries[plan] += 1
+            if "COLLSCAN" in plan:
+                self.collscan = True
+        if attr.get("hasSortStage"):
+            self.in_memory_sort = True
+        if not self.example:
+            self.example = entry.raw[:2000]
+
+    # -- derived metrics ---------------------------------------------------
+    @property
+    def total_ms(self) -> int:
+        return sum(self.durations)
+
+    @property
+    def mean_ms(self) -> float:
+        return self.total_ms / self.count if self.count else 0.0
+
+    @property
+    def max_ms(self) -> int:
+        return max(self.durations) if self.durations else 0
+
+    @property
+    def p95_ms(self) -> int:
+        if not self.durations:
+            return 0
+        ordered = sorted(self.durations)
+        idx = max(0, math.ceil(0.95 * len(ordered)) - 1)
+        return ordered[idx]
+
+    @property
+    def scan_ratio(self) -> float:
+        """docsExamined per document returned — the classic inefficiency signal."""
+        return self.docs_examined / self.n_returned if self.n_returned else float(
+            self.docs_examined or 0
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "ns": self.shape.ns,
+            "operation": self.shape.operation,
+            "shape": self.shape.pretty(),
+            "count": self.count,
+            "totalMs": self.total_ms,
+            "meanMs": round(self.mean_ms, 1),
+            "maxMs": self.max_ms,
+            "p95Ms": self.p95_ms,
+            "docsExamined": self.docs_examined,
+            "keysExamined": self.keys_examined,
+            "nReturned": self.n_returned,
+            "scanRatio": round(self.scan_ratio, 1),
+            "collscan": self.collscan,
+            "inMemorySort": self.in_memory_sort,
+            "planSummaries": dict(self.plan_summaries),
+        }
+
+
+class QueryAggregator:
+    def __init__(self, min_ms: int = 0):
+        self.min_ms = min_ms
+        self.shapes: Dict[QueryShape, ShapeStats] = {}
+
+    NOISE_OPS = frozenset({
+        "hello", "isMaster", "ismaster", "ping", "endSessions", "saslStart",
+        "saslContinue", "buildInfo", "getParameter", "serverStatus", "getLog",
+        "replSetGetStatus", "connPoolStats", "getCmdLineOpts", "whatsmyuri",
+        "logout", "killCursors", "listCollections", "listIndexes",
+        "listDatabases", "getFreeMonitoringStatus", "dbStats", "collStats",
+        "top", "currentOp", "profile", "hostInfo", "createIndexes",
+    })
+
+    def consume(self, entry: LogEntry):
+        if not entry.is_slow_query:
+            return
+        if int(entry.attr.get("durationMillis", 0) or 0) < self.min_ms:
+            return
+        shape = extract_shape(entry)
+        if shape is None or shape.operation == "insert":
+            return
+        if shape.operation in self.NOISE_OPS and not shape.filter_fields:
+            return
+        # Batched update/delete at COMMAND level often omits the per-op q;
+        # the paired WRITE entry carries the real shape and metrics.
+        if (shape.operation in ("update", "delete") and not shape.filter_fields
+                and entry.component == "COMMAND"):
+            return
+        stats = self.shapes.get(shape)
+        if stats is None:
+            stats = self.shapes[shape] = ShapeStats(shape=shape)
+        stats.add(entry)
+
+    def results(self, sort_by: str = "totalMs", limit: int = 0) -> List[ShapeStats]:
+        keymap = {
+            "duration": lambda s: s.total_ms,
+            "totalMs": lambda s: s.total_ms,
+            "count": lambda s: s.count,
+            "mean": lambda s: s.mean_ms,
+            "max": lambda s: s.max_ms,
+            "docsExamined": lambda s: s.docs_examined,
+            "scanRatio": lambda s: s.scan_ratio,
+        }
+        key = keymap.get(sort_by, keymap["totalMs"])
+        ordered = sorted(self.shapes.values(), key=key, reverse=True)
+        return ordered[:limit] if limit else ordered
+
+
+# ---------------------------------------------------------------------------
+# Connections
+# ---------------------------------------------------------------------------
+
+def _ip_of(remote: str) -> str:
+    return remote.rsplit(":", 1)[0] if remote else "unknown"
+
+
+@dataclass
+class ConnectionReport:
+    accepted: Counter = field(default_factory=Counter)
+    ended: Counter = field(default_factory=Counter)
+    app_names: Counter = field(default_factory=Counter)
+    drivers: Counter = field(default_factory=Counter)
+    peak_count: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "totalAccepted": sum(self.accepted.values()),
+            "totalEnded": sum(self.ended.values()),
+            "peakConnectionCount": self.peak_count,
+            "byIp": [
+                {"ip": ip, "accepted": n, "ended": self.ended.get(ip, 0)}
+                for ip, n in self.accepted.most_common()
+            ],
+            "appNames": dict(self.app_names.most_common()),
+            "drivers": dict(self.drivers.most_common()),
+        }
+
+
+class ConnectionAggregator:
+    def __init__(self):
+        self.report = ConnectionReport()
+
+    def consume(self, entry: LogEntry):
+        attr = entry.attr
+        if entry.msg_id == ID_CONN_ACCEPTED:
+            self.report.accepted[_ip_of(attr.get("remote", ""))] += 1
+            self.report.peak_count = max(
+                self.report.peak_count, int(attr.get("connectionCount", 0) or 0)
+            )
+        elif entry.msg_id == ID_CONN_ENDED:
+            self.report.ended[_ip_of(attr.get("remote", ""))] += 1
+            self.report.peak_count = max(
+                self.report.peak_count, int(attr.get("connectionCount", 0) or 0)
+            )
+        elif entry.msg_id == ID_CLIENT_METADATA:
+            doc = attr.get("doc", {}) or {}
+            app = (doc.get("application") or {}).get("name")
+            if app:
+                self.report.app_names[app] += 1
+            driver = (doc.get("driver") or {}).get("name")
+            if driver:
+                self.report.drivers[driver] += 1
+
+
+# ---------------------------------------------------------------------------
+# Whole-log summary (loginfo)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class LogSummary:
+    versions: List[str] = field(default_factory=list)
+    startups: int = 0
+    host_info: List[str] = field(default_factory=list)
+    severity_counts: Counter = field(default_factory=Counter)
+    component_counts: Counter = field(default_factory=Counter)
+    slow_queries: int = 0
+    slowest_ms: int = 0
+    connections_accepted: int = 0
+    warnings: int = 0
+    errors: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "startups": self.startups,
+            "versions": self.versions,
+            "hosts": self.host_info,
+            "slowQueries": self.slow_queries,
+            "slowestMs": self.slowest_ms,
+            "connectionsAccepted": self.connections_accepted,
+            "warnings": self.warnings,
+            "errors": self.errors,
+            "bySeverity": dict(self.severity_counts),
+            "byComponent": dict(self.component_counts.most_common()),
+        }
+
+
+class SummaryAggregator:
+    def __init__(self):
+        self.summary = LogSummary()
+
+    def consume(self, entry: LogEntry):
+        s = self.summary
+        s.severity_counts[entry.severity] += 1
+        s.component_counts[entry.component] += 1
+        if entry.severity == "W":
+            s.warnings += 1
+        elif entry.severity in ("E", "F"):
+            s.errors += 1
+        if entry.msg_id == ID_STARTUP:
+            s.startups += 1
+            host = entry.attr.get("host")
+            port = entry.attr.get("port")
+            if host:
+                s.host_info.append(f"{host}:{port}" if port else str(host))
+        elif entry.msg_id == ID_BUILD_INFO:
+            version = (entry.attr.get("buildInfo") or {}).get("version")
+            if version and version not in s.versions:
+                s.versions.append(version)
+        elif entry.msg_id == ID_CONN_ACCEPTED:
+            s.connections_accepted += 1
+        if entry.is_slow_query:
+            s.slow_queries += 1
+            s.slowest_ms = max(s.slowest_ms, int(entry.attr.get("durationMillis", 0) or 0))

mdbkit/cli.py

@@ -0,0 +1,256 @@
+"""mdbkit command-line interface.
+
+Fully offline: reads files/stdin, writes stdout. No network, no telemetry.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .advisor import advise, load_indexes, load_schema
+from .analysis import ConnectionAggregator, QueryAggregator, SummaryAggregator
+from .filtering import Filter, parse_when
+from .parser import PRE_44_HINT, ParseStats, iter_entries
+from .render import (
+    dump_json,
+    render_connections,
+    render_queries,
+    render_recommendations,
+    render_summary,
+)
+from .scripts import INDEXES_SCRIPT, SCHEMA_SCRIPT
+
+
+def _warn_if_pre44(stats: ParseStats) -> None:
+    if stats.total_lines and stats.unparsed_ratio > 0.5:
+        print(f"warning: {PRE_44_HINT}", file=sys.stderr)
+
+
+def cmd_loginfo(args) -> int:
+    stats = ParseStats()
+    agg = SummaryAggregator()
+    for entry in iter_entries(args.logfile, stats):
+        agg.consume(entry)
+    _warn_if_pre44(stats)
+    if args.json:
+        out = agg.summary.to_dict()
+        out["parse"] = {"lines": stats.total_lines, "parsed": stats.parsed,
+                        "unparsed": stats.unparsed}
+        print(dump_json(out))
+    else:
+        print(render_summary(agg.summary, stats))
+    return 0
+
+
+def cmd_queries(args) -> int:
+    stats = ParseStats()
+    agg = QueryAggregator(min_ms=args.min_ms)
+    for entry in iter_entries(args.logfile, stats):
+        agg.consume(entry)
+    _warn_if_pre44(stats)
+    results = agg.results(sort_by=args.sort, limit=args.limit)
+    if args.json:
+        print(dump_json([s.to_dict() for s in results]))
+    else:
+        print(render_queries(results, stats))
+    return 0
+
+
+def cmd_connections(args) -> int:
+    stats = ParseStats()
+    agg = ConnectionAggregator()
+    for entry in iter_entries(args.logfile, stats):
+        agg.consume(entry)
+    _warn_if_pre44(stats)
+    if args.json:
+        print(dump_json(agg.report.to_dict()))
+    else:
+        print(render_connections(agg.report, stats))
+    return 0
+
+
+def cmd_filter(args) -> int:
+    flt = Filter(
+        component=args.component,
+        severity=args.severity,
+        namespace=args.ns,
+        slow_ms=args.slow,
+        ts_from=parse_when(args.ts_from) if args.ts_from else None,
+        ts_to=parse_when(args.ts_to) if args.ts_to else None,
+        msg_contains=args.msg,
+    )
+    stats = ParseStats()
+    matched = 0
+    for entry in iter_entries(args.logfile, stats):
+        if flt.matches(entry):
+            print(entry.raw)
+            matched += 1
+    _warn_if_pre44(stats)
+    print(f"filter: matched {matched:,} of {stats.parsed:,} parsed lines",
+          file=sys.stderr)
+    return 0
+
+
+def cmd_advise(args) -> int:
+    stats = ParseStats()
+    agg = QueryAggregator(min_ms=args.min_ms)
+    for entry in iter_entries(args.logfile, stats):
+        agg.consume(entry)
+    _warn_if_pre44(stats)
+    indexes = load_indexes(args.indexes) if args.indexes else None
+    schema = load_schema(args.schema) if args.schema else None
+    recs = advise(agg.results(), indexes=indexes, schema=schema,
+                  min_count=args.min_count)
+    if not args.indexes:
+        print("note: no --indexes file given; overlap with existing indexes was "
+              "not checked. Export with: mdbkit export-script indexes",
+              file=sys.stderr)
+    if args.json:
+        print(dump_json([r.to_dict() for r in recs]))
+    else:
+        print(render_recommendations(recs, stats))
+    return 0
+
+
+def cmd_explain(args) -> int:
+    from .explain import analyze_explain, load_explain, render_explain
+    try:
+        doc = load_explain(args.explainfile)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    indexes = load_indexes(args.indexes) if args.indexes else None
+    schema = load_schema(args.schema) if args.schema else None
+    report = analyze_explain(doc, indexes=indexes, schema=schema)
+    if args.json:
+        print(dump_json(report.to_dict()))
+    else:
+        print(render_explain(report))
+    return 0
+
+
+def cmd_triage(args) -> int:
+    from .triage import render_triage, run_triage
+    findings, stats, cutoff = run_triage(
+        args.logfile, window_min=args.window, dbpath=args.dbpath,
+        no_sysprobe=args.no_sysprobe)
+    _warn_if_pre44(stats)
+    if args.json:
+        print(dump_json({
+            "window": {"from": cutoff or stats.first_ts, "to": stats.last_ts},
+            "findings": [f.to_dict() for f in findings],
+        }))
+    else:
+        print(render_triage(findings, stats, cutoff))
+    return 0
+
+
+def cmd_export_script(args) -> int:
+    print(SCHEMA_SCRIPT if args.kind == "schema" else INDEXES_SCRIPT)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="mdbkit",
+        description=(
+            "Offline toolkit for MongoDB 4.4+ structured logs: log summaries, "
+            "slow-query analysis, connection churn, log filtering, and "
+            "deterministic candidate-index advice. A spiritual successor to "
+            "mtools' log tools. Never connects to a network."
+        ),
+    )
+    p.add_argument("--version", action="version", version=f"mdbkit {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def add_common(sp):
+        sp.add_argument("logfile", help="path to mongod/mongos log (.log or .gz), or '-' for stdin")
+        sp.add_argument("--json", action="store_true", help="machine-readable JSON output")
+
+    sp = sub.add_parser("loginfo", help="overall log summary (versions, restarts, counts)")
+    add_common(sp)
+    sp.set_defaults(func=cmd_loginfo)
+
+    sp = sub.add_parser("queries", help="group and rank slow queries by shape")
+    add_common(sp)
+    sp.add_argument("--sort", default="totalMs",
+                    choices=["totalMs", "duration", "count", "mean", "max",
+                             "docsExamined", "scanRatio"])
+    sp.add_argument("--limit", type=int, default=0, help="show top N shapes")
+    sp.add_argument("--min-ms", type=int, default=0,
+                    help="ignore operations faster than this")
+    sp.set_defaults(func=cmd_queries)
+
+    sp = sub.add_parser("connections", help="connection churn by source IP and app")
+    add_common(sp)
+    sp.set_defaults(func=cmd_connections)
+
+    sp = sub.add_parser("filter", help="stream matching raw log lines (chainable)")
+    sp.add_argument("logfile")
+    sp.add_argument("--component", help="e.g. COMMAND, NETWORK, REPL")
+    sp.add_argument("--severity", help="I, W, E, F")
+    sp.add_argument("--ns", help="exact namespace, e.g. shop.orders")
+    sp.add_argument("--slow", type=int, help="only ops with durationMillis >= N")
+    sp.add_argument("--from", dest="ts_from", help="ISO timestamp lower bound")
+    sp.add_argument("--to", dest="ts_to", help="ISO timestamp upper bound")
+    sp.add_argument("--msg", help="substring match on the msg field")
+    sp.set_defaults(func=cmd_filter)
+
+    sp = sub.add_parser("advise", help="deterministic candidate-index recommendations")
+    add_common(sp)
+    sp.add_argument("--indexes", help="indexes.json from `mdbkit export-script indexes`")
+    sp.add_argument("--schema", help="schema.json from `mdbkit export-script schema`")
+    sp.add_argument("--min-ms", type=int, default=0)
+    sp.add_argument("--min-count", type=int, default=1,
+                    help="only advise on shapes seen at least N times")
+    sp.set_defaults(func=cmd_advise)
+
+    sp = sub.add_parser("explain",
+                        help="analyze a saved explain('executionStats') JSON file")
+    sp.add_argument("explainfile",
+                    help="explain output saved as JSON (mongosh EJSON.stringify "
+                         "or Compass export)")
+    sp.add_argument("--json", action="store_true", help="machine-readable output")
+    sp.add_argument("--indexes", help="indexes.json for overlap checks")
+    sp.add_argument("--schema", help="schema.json for field caveats")
+    sp.set_defaults(func=cmd_explain)
+
+    sp = sub.add_parser("triage",
+                        help="one-command incident snapshot (beta): elections, "
+                             "storms, hot collections, errors + local disk/"
+                             "memory/load probes")
+    sp.add_argument("logfile", help="mongod log (.log or .gz), or '-'")
+    sp.add_argument("--window", type=int, metavar="MINUTES",
+                    help="analyze only the last N minutes of log time "
+                         "(default: whole file)")
+    sp.add_argument("--dbpath", help="override dbPath for the disk probe")
+    sp.add_argument("--no-sysprobe", action="store_true",
+                    help="skip local disk/memory/load probes")
+    sp.add_argument("--json", action="store_true")
+    sp.set_defaults(func=cmd_triage)
+
+    sp = sub.add_parser("export-script",
+                        help="print a mongosh script to export schema or indexes")
+    sp.add_argument("kind", choices=["schema", "indexes"])
+    sp.set_defaults(func=cmd_export_script)
+
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())