apppack-stats 0.2.0__tar.gz

apppack_stats-0.2.0/.gitignore

@@ -0,0 +1,27 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.python-version
+uv.lock
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store

apppack_stats-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Mahner <martin@elephant.house>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apppack_stats-0.2.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: apppack-stats
+Version: 0.2.0
+Summary: Live response-time stats from streamed AppPack web logs.
+Project-URL: Homepage, https://github.com/lincolnloop/apppack-stats
+Project-URL: Issues, https://github.com/lincolnloop/apppack-stats/issues
+Author-email: Martin Burchell <martin@lincolnloop.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apppack,logs,monitoring,observability,stats
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: rich>=13
+Requires-Dist: textual>=0.50
+Description-Content-Type: text/markdown
+
+# apppack-stats
+
+Live response-time stats from streamed [AppPack](https://apppack.io) web logs.
+
+`apppack-stats` shells out to `apppack logs --raw --follow` for the app you
+name, parses the JSON request lines, and renders a live [Textual] data
+table grouped by `(method, normalized path)`. Click any column header to
+re-sort by it; click again to flip the direction.
+
+[Textual]: https://textual.textualize.io/
+
+```
+Slowest endpoints — 1842/1903 lines parsed, 47s elapsed
+┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━┓
+┃ Method ┃ Path                          ┃ Count ┃ Avg ms ┃ p95 ms ┃ Max ms ┃ Err ┃
+┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━┩
+│ GET    │ /reports/<id>/export          │     7 │   1842 │   2210 │   2480 │     │
+│ POST   │ /api/v1/orders                │    23 │    412 │    711 │    980 │   2 │
+│ GET    │ /dashboard                    │    91 │    188 │    320 │    640 │     │
+└────────┴───────────────────────────────┴───────┴────────┴────────┴────────┴─────┘
+```
+
+## Usage
+
+No install required — run it straight from PyPI with
+[`uv`](https://docs.astral.sh/uv/):
+
+```sh
+uvx apppack-stats <appname>
+```
+
+Press `q` (or `Ctrl+C`) to stop; a final summary table is printed once on exit.
+
+### Keys
+
+| Key                 | Action                                       |
+| ------------------- | -------------------------------------------- |
+| Click column header | Sort by that column (click again to reverse) |
+| `n`                 | Toggle URL normalization on/off              |
+| `q`                 | Quit                                         |
+
+The [AppPack CLI](https://docs.apppack.io/how-to/install-the-cli/) must be on
+your `PATH` and authenticated against the account that owns the app.
+
+## Options
+
+| Flag              | Default | Notes                                               |
+| ----------------- | ------- | --------------------------------------------------- |
+| `--refresh SEC`   | `1.0`   | Seconds between redraws                             |
+| `--start DUR`     | `5m`    | How far back to seed history (`30m`, `2h`, `1d`, …) |
+| `--prefix STRING` | _none_  | AppPack log-group prefix filter — see note below    |
+| `--no-normalize`  | off     | Group by raw path instead of normalizing IDs        |
+
+The table fills the terminal and scrolls when there are more rows than fit.
+
+### A note on `--prefix`
+
+`apppack logs --prefix` filters on AppPack's underlying CloudWatch
+log-group names, which don't always begin with the service name shown in
+the rendered `(web/web/<task>)` label. Different AppPack apps use
+different log-group naming conventions, so a fixed default like `web`
+silently drops everything for some apps. By default `apppack-stats`
+passes no prefix and lets the parser filter — only access-log JSON lines
+(those with `method`, `path`, `status`, `response_time_us`) are counted;
+everything else is skipped.
+
+## URL normalization
+
+By default, paths are normalized so that `/orders/12345` and `/orders/67890`
+share a row as `/orders/<id>`. UUIDs become `/<uuid>`, long hex hashes
+become `/<hash>`. Pass `--no-normalize` to keep raw paths.

apppack_stats-0.2.0/README.md

@@ -0,0 +1,71 @@
+# apppack-stats
+
+Live response-time stats from streamed [AppPack](https://apppack.io) web logs.
+
+`apppack-stats` shells out to `apppack logs --raw --follow` for the app you
+name, parses the JSON request lines, and renders a live [Textual] data
+table grouped by `(method, normalized path)`. Click any column header to
+re-sort by it; click again to flip the direction.
+
+[Textual]: https://textual.textualize.io/
+
+```
+Slowest endpoints — 1842/1903 lines parsed, 47s elapsed
+┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━┓
+┃ Method ┃ Path                          ┃ Count ┃ Avg ms ┃ p95 ms ┃ Max ms ┃ Err ┃
+┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━┩
+│ GET    │ /reports/<id>/export          │     7 │   1842 │   2210 │   2480 │     │
+│ POST   │ /api/v1/orders                │    23 │    412 │    711 │    980 │   2 │
+│ GET    │ /dashboard                    │    91 │    188 │    320 │    640 │     │
+└────────┴───────────────────────────────┴───────┴────────┴────────┴────────┴─────┘
+```
+
+## Usage
+
+No install required — run it straight from PyPI with
+[`uv`](https://docs.astral.sh/uv/):
+
+```sh
+uvx apppack-stats <appname>
+```
+
+Press `q` (or `Ctrl+C`) to stop; a final summary table is printed once on exit.
+
+### Keys
+
+| Key                 | Action                                       |
+| ------------------- | -------------------------------------------- |
+| Click column header | Sort by that column (click again to reverse) |
+| `n`                 | Toggle URL normalization on/off              |
+| `q`                 | Quit                                         |
+
+The [AppPack CLI](https://docs.apppack.io/how-to/install-the-cli/) must be on
+your `PATH` and authenticated against the account that owns the app.
+
+## Options
+
+| Flag              | Default | Notes                                               |
+| ----------------- | ------- | --------------------------------------------------- |
+| `--refresh SEC`   | `1.0`   | Seconds between redraws                             |
+| `--start DUR`     | `5m`    | How far back to seed history (`30m`, `2h`, `1d`, …) |
+| `--prefix STRING` | _none_  | AppPack log-group prefix filter — see note below    |
+| `--no-normalize`  | off     | Group by raw path instead of normalizing IDs        |
+
+The table fills the terminal and scrolls when there are more rows than fit.
+
+### A note on `--prefix`
+
+`apppack logs --prefix` filters on AppPack's underlying CloudWatch
+log-group names, which don't always begin with the service name shown in
+the rendered `(web/web/<task>)` label. Different AppPack apps use
+different log-group naming conventions, so a fixed default like `web`
+silently drops everything for some apps. By default `apppack-stats`
+passes no prefix and lets the parser filter — only access-log JSON lines
+(those with `method`, `path`, `status`, `response_time_us`) are counted;
+everything else is skipped.
+
+## URL normalization
+
+By default, paths are normalized so that `/orders/12345` and `/orders/67890`
+share a row as `/orders/<id>`. UUIDs become `/<uuid>`, long hex hashes
+become `/<hash>`. Pass `--no-normalize` to keep raw paths.

apppack_stats-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apppack-stats"
+version = "0.2.0"
+description = "Live response-time stats from streamed AppPack web logs."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Martin Burchell", email = "martin@lincolnloop.com" }]
+keywords = ["apppack", "logs", "stats", "monitoring", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Topic :: System :: Logging",
+]
+dependencies = [
+    "rich>=13",
+    "textual>=0.50",
+]
+
+[project.scripts]
+apppack-stats = "apppack_stats:main"
+
+[project.urls]
+Homepage = "https://github.com/lincolnloop/apppack-stats"
+Issues = "https://github.com/lincolnloop/apppack-stats/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apppack_stats"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]

apppack_stats-0.2.0/src/apppack_stats/__init__.py

@@ -0,0 +1,353 @@
+"""Live response-time stats from streamed AppPack web logs.
+
+Spawns ``apppack logs --raw --follow`` for the requested app and aggregates
+incoming requests per ``(method, normalized path)`` into a sortable Textual
+data table. Click any column header to sort by it; click again to reverse.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import statistics
+import subprocess
+import sys
+import threading
+from collections import defaultdict
+from dataclasses import dataclass, field
+from time import monotonic
+from typing import IO
+
+from rich.console import Console
+from rich.table import Table
+from textual.app import App, ComposeResult
+from textual.widgets import DataTable, Footer, Header
+
+__version__ = "0.2.0"
+
+# Order matters: UUIDs and hex hashes before bare ints.
+_UUID_RE = re.compile(
+    r"/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=/|$)", re.I
+)
+_HEX_RE = re.compile(r"/[0-9a-f]{16,}(?=/|$)", re.I)
+_INT_RE = re.compile(r"/\d+(?=/|$)")
+
+
+def normalize_path(path: str) -> str:
+    path = _UUID_RE.sub("/<uuid>", path)
+    path = _HEX_RE.sub("/<hash>", path)
+    path = _INT_RE.sub("/<id>", path)
+    return path
+
+
+@dataclass
+class Bucket:
+    count: int = 0
+    errors: int = 0
+    times_us: list[int] = field(default_factory=list)
+
+    def add(self, time_us: int, status: int) -> None:
+        self.count += 1
+        self.times_us.append(time_us)
+        if status >= 400:
+            self.errors += 1
+
+    @property
+    def avg_ms(self) -> float:
+        return statistics.fmean(self.times_us) / 1000
+
+    @property
+    def p95_ms(self) -> float:
+        if len(self.times_us) < 2:
+            return self.times_us[0] / 1000
+        return statistics.quantiles(self.times_us, n=20)[18] / 1000
+
+    @property
+    def max_ms(self) -> float:
+        return max(self.times_us) / 1000
+
+
+class Stats:
+    def __init__(self, *, normalize: bool) -> None:
+        self.normalize = normalize
+        self.buckets: dict[tuple[str, str], Bucket] = defaultdict(Bucket)
+        self.total_lines = 0
+        self.parsed_lines = 0
+        self.started = monotonic()
+        self.lock = threading.Lock()
+
+    def ingest(self, line: str) -> None:
+        self.total_lines += 1
+        line = line.strip()
+        if not line or line[0] != "{":
+            return
+        try:
+            payload = json.loads(line)
+            method = payload["method"]
+            path = payload["path"]
+            time_us = int(payload["response_time_us"])
+            status = int(payload["status"])
+        except (ValueError, KeyError, TypeError):
+            return
+
+        if self.normalize:
+            path = normalize_path(path)
+
+        with self.lock:
+            self.buckets[(method, path)].add(time_us, status)
+            self.parsed_lines += 1
+
+    def summary_table(self, *, sort_col: str, reverse: bool) -> Table:
+        with self.lock:
+            items = list(self.buckets.items())
+            elapsed = monotonic() - self.started
+            total = self.total_lines
+            parsed = self.parsed_lines
+        items.sort(key=_SORT_KEYS[sort_col], reverse=reverse)
+
+        table = Table(
+            title=f"apppack-stats — {parsed}/{total} lines, {elapsed:.0f}s elapsed",
+            caption=f"sort: {sort_col} {'↓' if reverse else '↑'}",
+        )
+        table.add_column("Method", style="cyan", no_wrap=True)
+        table.add_column("Path", style="white", overflow="fold")
+        table.add_column("Count", justify="right", style="dim")
+        table.add_column("Avg ms", justify="right", style="bold yellow")
+        table.add_column("p95 ms", justify="right")
+        table.add_column("Max ms", justify="right")
+        table.add_column("Err", justify="right", style="red")
+        for (method, path), bucket in items:
+            table.add_row(
+                method,
+                path,
+                str(bucket.count),
+                f"{bucket.avg_ms:.0f}",
+                f"{bucket.p95_ms:.0f}",
+                f"{bucket.max_ms:.0f}",
+                str(bucket.errors) if bucket.errors else "",
+            )
+        return table
+
+
+# Column key -> sort key over (key, bucket) tuples.
+_SORT_KEYS: dict[str, "callable"] = {
+    "method": lambda kv: kv[0][0],
+    "path": lambda kv: kv[0][1],
+    "count": lambda kv: kv[1].count,
+    "avg": lambda kv: kv[1].avg_ms,
+    "p95": lambda kv: kv[1].p95_ms,
+    "max": lambda kv: kv[1].max_ms,
+    "err": lambda kv: kv[1].errors,
+}
+
+_NUMERIC_COLS = {"count", "avg", "p95", "max", "err"}
+
+
+def _reader_thread(stats: Stats, stream: IO[str], stop: threading.Event) -> None:
+    for line in stream:
+        if stop.is_set():
+            break
+        stats.ingest(line)
+    stop.set()
+
+
+class StatsApp(App):
+    """Textual UI for live response-time stats."""
+
+    CSS = """
+    DataTable {
+        height: 1fr;
+    }
+    """
+
+    BINDINGS = [
+        ("q", "quit", "Quit"),
+        ("n", "toggle_normalize", "Toggle path normalization"),
+    ]
+
+    def __init__(
+        self,
+        stats: Stats,
+        *,
+        refresh: float,
+        proc: subprocess.Popen,
+    ) -> None:
+        super().__init__()
+        self.stats = stats
+        self.refresh_sec = refresh
+        self.proc = proc
+        self.sort_col = "avg"
+        self.sort_reverse = True
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield DataTable(zebra_stripes=True, cursor_type="row")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        table = self.query_one(DataTable)
+        table.add_column("Method", key="method", width=8)
+        table.add_column("Path", key="path")
+        table.add_column("Count", key="count", width=8)
+        table.add_column("Avg ms", key="avg", width=8)
+        table.add_column("p95 ms", key="p95", width=8)
+        table.add_column("Max ms", key="max", width=8)
+        table.add_column("Err", key="err", width=6)
+        self.title = "apppack-stats"
+        self._update_subtitle()
+        self.set_interval(self.refresh_sec, self._tick)
+        self._tick()
+
+    def on_data_table_header_selected(
+        self, event: DataTable.HeaderSelected
+    ) -> None:
+        col_key = str(event.column_key.value) if event.column_key else ""
+        if col_key not in _SORT_KEYS:
+            return
+        if col_key == self.sort_col:
+            self.sort_reverse = not self.sort_reverse
+        else:
+            self.sort_col = col_key
+            self.sort_reverse = col_key in _NUMERIC_COLS
+        self._update_subtitle()
+        self._tick()
+
+    def action_toggle_normalize(self) -> None:
+        with self.stats.lock:
+            self.stats.normalize = not self.stats.normalize
+        self._update_subtitle()
+
+    def _update_subtitle(self) -> None:
+        arrow = "↓" if self.sort_reverse else "↑"
+        norm = "" if self.stats.normalize else "  (raw paths)"
+        self.sub_title = f"sort: {self.sort_col} {arrow}{norm}"
+
+    def _tick(self) -> None:
+        if self.proc.poll() is not None:
+            self.exit()
+            return
+        with self.stats.lock:
+            items = list(self.stats.buckets.items())
+            elapsed = monotonic() - self.stats.started
+            total = self.stats.total_lines
+            parsed = self.stats.parsed_lines
+        items.sort(key=_SORT_KEYS[self.sort_col], reverse=self.sort_reverse)
+
+        table = self.query_one(DataTable)
+        table.clear()
+        for (method, path), bucket in items:
+            table.add_row(
+                method,
+                path,
+                str(bucket.count),
+                f"{bucket.avg_ms:.0f}",
+                f"{bucket.p95_ms:.0f}",
+                f"{bucket.max_ms:.0f}",
+                str(bucket.errors) if bucket.errors else "",
+            )
+        self.title = f"apppack-stats — {parsed}/{total} lines, {elapsed:.0f}s"
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="apppack-stats",
+        description="Live response-time stats from an AppPack web service.",
+    )
+    parser.add_argument("app", help="AppPack app name")
+    parser.add_argument(
+        "--refresh",
+        type=float,
+        default=1.0,
+        help="seconds between redraws (default: 1.0)",
+    )
+    parser.add_argument(
+        "--start",
+        default="5m",
+        help="how far back to seed history, e.g. 30m, 2h, 1d (default: 5m)",
+    )
+    parser.add_argument(
+        "--prefix",
+        default=None,
+        help=(
+            "log group prefix filter passed to `apppack logs --prefix`. "
+            "By default no filter is applied — non-access-log lines are "
+            "skipped by the parser anyway."
+        ),
+    )
+    parser.add_argument(
+        "--no-normalize",
+        dest="normalize",
+        action="store_false",
+        help="disable URL normalization (group by raw path)",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+
+    if shutil.which("apppack") is None:
+        sys.stderr.write(
+            "error: 'apppack' CLI not found on PATH.\n"
+            "Install it from https://docs.apppack.io/how-to/install-the-cli/\n"
+        )
+        return 2
+
+    cmd = [
+        "apppack", "logs",
+        "-a", args.app,
+        "--follow",
+        "--raw",
+        "--start", args.start,
+    ]
+    if args.prefix:
+        cmd += ["--prefix", args.prefix]
+
+    proc = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+    )
+    assert proc.stdout is not None
+
+    stats = Stats(normalize=args.normalize)
+    stop = threading.Event()
+    reader = threading.Thread(
+        target=_reader_thread, args=(stats, proc.stdout, stop), daemon=True
+    )
+    reader.start()
+
+    app = StatsApp(stats, refresh=args.refresh, proc=proc)
+    try:
+        app.run()
+    finally:
+        stop.set()
+        proc.terminate()
+        try:
+            proc.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+
+    Console().print(
+        stats.summary_table(sort_col=app.sort_col, reverse=app.sort_reverse)
+    )
+
+    rc = proc.returncode or 0
+    if rc not in (0, -15):
+        stderr = proc.stderr.read() if proc.stderr else ""
+        if stderr:
+            sys.stderr.write(stderr)
+        return rc
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())