mdbkit 0.2.0__tar.gz → 0.2.1__tar.gz

{mdbkit-0.2.0/mdbkit.egg-info → mdbkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdbkit
-Version: 0.2.0
+Version: 0.2.1
 Summary: Offline toolkit for MongoDB 4.4+ structured logs: log analysis, slow-query shapes, connection churn, and deterministic index advice. A spiritual successor to mtools' log tools.
 Author: Saqib Ameen Subhan
 License: MIT
@@ -295,7 +295,7 @@ query with different parameters is counted once.
 | `--limit N` | all | Show only the top N shapes |
 | `--min-ms N` | 0 | Ignore operations faster than N milliseconds |
 | `--include-system` | off | Include internal `admin`/`config`/`local` namespaces (hidden by default — they are server housekeeping, not your workload) |
-| `--report FILE` | | Write a shareable `.md` or `.html` report instead |
+| `--report FILE` | | Write a shareable `.md` or `.html` report instead (see [Shareable reports](#shareable-reports----report-file)) |
 | `--json` | | Machine-readable output |
 
 **Reading the columns:**
@@ -500,11 +500,21 @@ not encrypted; mdbkit decodes it offline.
 
 | Option | Default | Description |
 |---|---|---|
+| `--last DURATION` | `4h` | Analyze only the most recent window — `90m`, `4h`, `2d` |
+| `--all` | off | Analyze the entire history (see the performance note below) |
 | `--metric LABEL` | all | Restrict to one metric (repeatable), e.g. `--metric conns.current` |
 | `--step SECONDS` | 60 | Timeline bucket size |
-| `--from` / `--to` | | Time bounds (same formats as `filter`) |
+| `--from` / `--to` | | Explicit time bounds (same formats as `filter`) |
 | `--json` | | Machine-readable output |
 
+**Performance note.** `diagnostic.data` can hold weeks of per-second samples —
+a few hundred megabytes covering thousands of chunks and several thousand
+metrics each. Decoding all of it is CPU-bound and takes minutes, so these
+commands **default to the last 4 hours** and skip older chunks before
+decompressing them. On a 250 MB directory that is the difference between about
+a second and about a minute. Use `--last`/`--from`/`--to` to move the window,
+and `--all` when you really do want the whole history.
+
 ```bash
 mdbkit ftdc summary /var/lib/mongodb/diagnostic.data
 mdbkit ftdc timeline diagnostic.data --metric conns.current --step 300
@@ -521,6 +531,47 @@ contains metrics only, never document contents.
 
 ---
 
+### Shareable reports — `--report FILE`
+
+`triage` and `queries` can write a self-contained report instead of printing to
+the terminal — for a ticket, a handover, or a post-incident review.
+
+```bash
+mdbkit triage mongod.log --report incident.html     # styled, self-contained
+mdbkit triage mongod.log --report incident.md       # for tickets and PRs
+mdbkit queries mongod.log --limit 20 --report slow-queries.md
+```
+
+The format follows the file extension: `.html` or `.md`.
+
+Markdown output looks like this:
+
+```markdown
+# MongoDB incident triage
+
+*window 2026-07-01 08:10 -> 09:10  ·  generated 2026-07-01 09:12*
+
+## Findings
+
+- **[CRIT] Replica set instability** — 3 election/stepdown event(s) at 08:41:02, 08:58:14
+    - Starting an election, since we've seen no PRIMARY in election timeout period
+    - *next:* `Correlate with connection storms and slow checkpoints below`
+- **[WARN] Connection storm** — 2 minute(s) at >= 60 new connections/min; peak 480 at 08:41
+    - 10.2.1.7: 312 in the peak minute
+    - *next:* `mdbkit connections <log>`
+- **[OK] Errors** — No error/fatal severity lines in window.
+```
+
+The HTML version carries the same content with a dark, print-friendly
+stylesheet. It is **fully self-contained**: inline CSS, no JavaScript, no
+external assets or CDN references, so it opens on an air-gapped machine and
+sends nothing anywhere.
+
+Reports contain the same information as the terminal output — query **shapes**
+and metrics, never literal values from your documents.
+
+---
+
 ### `mdbkit export-script {schema|indexes}`
 
 Prints a small `mongosh` script to stdout. **mdbkit never connects to your