logometer 0.1.0__py3-none-any.whl

logometer/__init__.py

@@ -0,0 +1,3 @@
+"""logometer — tail your logs, catch anomalies, skip the 2am grep."""
+
+__version__ = "0.1.0"

logometer/baseline.py

@@ -0,0 +1,54 @@
+"""
+A small rolling baseline: keeps the last N observed values for a metric
+(e.g. error count per window) and reports the mean/std of that history.
+
+Deliberately simple — a moving window of raw values, not an
+exponentially-weighted or Bayesian estimator. Easy to explain, easy to
+reason about when it gets something wrong.
+"""
+from __future__ import annotations
+
+import statistics
+from collections import deque
+
+
+class RollingBaseline:
+    def __init__(self, history_size: int = 20):
+        """Keep a fixed-size deque of recent metric samples (e.g. errors per window).
+        Older values drop off automatically when history_size is exceeded."""
+        self._values: deque[float] = deque(maxlen=history_size)
+
+    def update(self, value: float) -> None:
+        """Append one observation; drop the oldest when history exceeds history_size.
+        Called after each non-spike window in AnomalyDetector.evaluate."""
+        self._values.append(value)
+
+    @property
+    def ready(self) -> bool:
+        """True once there are enough samples to compare against (>= 3).
+        Until ready, deviation_score returns 0 and spikes are not scored."""
+        return len(self._values) >= 3
+
+    @property
+    def mean(self) -> float:
+        """Arithmetic mean of stored samples, or 0.0 if history is empty.
+        Shown in CLI output as the approximate errors-per-window baseline."""
+        if not self._values:
+            return 0.0
+        return statistics.fmean(self._values)
+
+    @property
+    def stdev(self) -> float:
+        """Population standard deviation of stored samples, or 0.0 if fewer than two.
+        Used with mean inside deviation_score for spike detection."""
+        if len(self._values) < 2:
+            return 0.0
+        return statistics.pstdev(self._values)
+
+    def deviation_score(self, value: float, min_stdev: float = 1.0) -> float:
+        """Return how many std devs above the mean `value` is (0 if not ready).
+        Uses max(stdev, min_stdev) so flat histories do not over-flag single events."""
+        if not self.ready:
+            return 0.0
+        std = max(self.stdev, min_stdev)
+        return (value - self.mean) / std

logometer/classifier.py

@@ -0,0 +1,71 @@
+"""
+Classifies a single log line into a severity level, and produces a
+"shape" fingerprint for error/warn lines so that structurally similar
+messages (same error, different id/timestamp/number) collapse into the
+same bucket.
+
+This is intentionally simple regex/heuristic matching, not a trained
+model — the goal is to be transparent and predictable, not clever.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Checked in this order — first match wins. ERROR-ish tokens must be
+# checked before WARN/INFO so a line like "ERROR: retrying after warning"
+# is classified as ERROR, not WARN.
+_LEVEL_PATTERNS = [
+    ("ERROR", re.compile(r"\b(error|err|fatal|critical|exception|traceback|panic)\b", re.IGNORECASE)),
+    ("WARN", re.compile(r"\b(warn|warning)\b", re.IGNORECASE)),
+    ("INFO", re.compile(r"\b(info|notice)\b", re.IGNORECASE)),
+    ("DEBUG", re.compile(r"\b(debug|trace)\b", re.IGNORECASE)),
+]
+
+# Patterns stripped out (in order) when building a fingerprint, so that
+# two error lines differing only in a request id / timestamp / number
+# are recognized as "the same shape".
+_FINGERPRINT_STRIPS = [
+    re.compile(r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b"),  # UUID
+    re.compile(r"\b0x[0-9a-fA-F]+\b"),  # hex addresses
+    re.compile(r"\b\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?(?:Z|[+-]\d{2}:?\d{2})?\b"),  # ISO timestamp (Python logging uses a comma before millis)
+    re.compile(r'"[^"]*"'),  # quoted strings
+    re.compile(r"'[^']*'"),  # single-quoted strings
+    re.compile(r"\d+"),  # numbers, including ones glued to units/words (e.g. "313ms", "Errno104")
+]
+
+
+@dataclass(frozen=True)
+class ClassifiedLine:
+    raw: str
+    level: str  # ERROR / WARN / INFO / DEBUG / UNKNOWN
+    shape: str | None  # only set for ERROR / WARN lines; None otherwise
+
+
+def classify_level(line: str) -> str:
+    """Tag a log line with ERROR/WARN/INFO/DEBUG via regex; UNKNOWN if no match.
+    Patterns are checked in priority order so ERROR wins over WARN on the same line."""
+    for level, pattern in _LEVEL_PATTERNS:
+        if pattern.search(line):
+            return level
+    return "UNKNOWN"
+
+
+def fingerprint(line: str) -> str:
+    """Normalize a line to an error/warn shape by stripping ids, numbers, and quotes.
+    Similar messages with different volatile tokens collapse to the same string."""
+    text = line.strip()
+    for pattern in _FINGERPRINT_STRIPS:
+        text = pattern.sub("<x>", text)
+    # collapse repeated whitespace and cap length so pathologically long
+    # lines don't blow up memory in the "seen shapes" set
+    text = re.sub(r"\s+", " ", text).strip()
+    return text[:200]
+
+
+def classify_line(line: str) -> ClassifiedLine:
+    """Classify severity and attach a shape fingerprint for ERROR/WARN lines.
+    INFO/DEBUG/UNKNOWN lines get shape=None."""
+    level = classify_level(line)
+    shape = fingerprint(line) if level in ("ERROR", "WARN") else None
+    return ClassifiedLine(raw=line, level=level, shape=shape)

logometer/cli.py

@@ -0,0 +1,447 @@
+"""
+logometer CLI — Day 1 scope: `logometer tail <file>`.
+
+Pure stdlib (argparse, no typer/rich dependency) so the tool runs with
+nothing but Python installed. --explain (LLM-powered) and prettier
+rich-based output are Day 2 additions.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import signal
+import sys
+import threading
+import time
+from queue import Empty, Queue
+from typing import Iterator, Pattern, TextIO
+
+from . import __version__
+from .detector import AnomalyDetector, AnomalyVerdict
+from .explain import ExplainError, explain_window
+from .pretty import HAS_RICH
+from .windower import Window, WindowAggregator
+
+_RED = "\033[91m"
+_DIM = "\033[2m"
+_YELLOW = "\033[93m"
+_CYAN = "\033[96m"
+_RESET = "\033[0m"
+
+_POLL_INTERVAL_SECONDS = 0.5
+
+
+def _supports_color(stream: TextIO) -> bool:
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def _flush(stream: TextIO) -> None:
+    """Push buffered output out now. Never raises — a closed or exotic
+    stream must not take down a tailing run."""
+    try:
+        stream.flush()
+    except (AttributeError, ValueError, OSError):
+        pass
+
+
+def _iter_stdin() -> Iterator[str | None]:
+    """Yield lines from stdin, plus a None "idle tick" whenever nothing
+    arrives for a poll interval, so a window can still close when the
+    upstream producer goes quiet.
+
+    A reader thread is used rather than select(): Python buffers stdin
+    internally, so select() on the file descriptor can report "no data"
+    while whole lines already sit in that buffer, waiting.
+    """
+    queue: Queue[str | None] = Queue()
+
+    def reader() -> None:
+        try:
+            for line in sys.stdin:
+                queue.put(line)
+        finally:
+            queue.put(None)  # sentinel: end of input
+
+    threading.Thread(target=reader, daemon=True).start()
+
+    while True:
+        try:
+            item = queue.get(timeout=_POLL_INTERVAL_SECONDS)
+        except Empty:
+            yield None  # nothing upstream right now — let windows close
+            continue
+        if item is None:
+            return
+        yield item
+
+
+def _iter_file_replay(path: str) -> Iterator[str]:
+    with open(path, "r", errors="replace") as f:
+        for line in f:
+            yield line
+
+
+def _file_identity(path: str) -> tuple[int, int] | None:
+    """(device, inode) for a path, or None if it isn't there right now."""
+    try:
+        st = os.stat(path)
+    except OSError:
+        return None
+    return (st.st_dev, st.st_ino)
+
+
+def _iter_file_live(path: str, poll_interval: float = _POLL_INTERVAL_SECONDS) -> Iterator[str | None]:
+    """Classic tail -f polling loop: seek to EOF, then poll for appended
+    lines, yielding None while idle so windows can close on time.
+
+    Also survives log rotation. Holding one file handle forever means
+    that after logrotate moves the file aside, we keep reading a
+    now-orphaned inode and silently see nothing ever again — so each
+    idle poll checks whether the path points somewhere new (rotated) or
+    has shrunk (truncated in place) and reopens accordingly.
+
+    Opened in binary mode on purpose: it gives an exact byte position, which
+    is what makes the truncation check reliable, and it lets a half-written
+    line (one whose newline hasn't been flushed yet) be held back instead of
+    handed over as though it were complete.
+    """
+    f = open(path, "rb")
+    try:
+        f.seek(0, 2)  # seek to end
+        identity = _file_identity(path)
+
+        while True:
+            chunk = f.readline()
+            if chunk.endswith(b"\n"):
+                yield chunk.decode("utf-8", errors="replace")
+                continue
+            if chunk:
+                # partial line — rewind and wait for the writer to finish it
+                f.seek(-len(chunk), os.SEEK_CUR)
+
+            time.sleep(poll_interval)
+
+            current = _file_identity(path)
+            if current is None:
+                yield None  # mid-rotation; the path will be back shortly
+                continue
+            if current != identity:
+                f.close()
+                f = open(path, "rb")  # new file: read it from the top
+                identity = current
+            elif os.stat(path).st_size < f.tell():
+                # truncated in place (copytruncate). Caveat: if the file is
+                # emptied and then refilled past our read offset inside one
+                # poll interval, the shrink is never observable by size and
+                # we resume mid-file — the same blind spot GNU tail has.
+                f.seek(0)
+
+            yield None
+    finally:
+        f.close()
+
+
+def _shape_levels(window: Window) -> dict[str, str]:
+    """Map each shape in a window back to the level of the line that produced it,
+    so a WARN-triggered anomaly isn't reported as an 'error signature'."""
+    return {l.shape: l.level for l in window.lines if l.shape}
+
+
+def _signature_label(level: str) -> str:
+    return "warning" if level == "WARN" else "error"
+
+
+def _format_plain(window: Window, verdict: AnomalyVerdict, color: bool, explanation: str | None = None) -> str:
+    label = f"[{window.start_label} \u2013 {window.end_label}]"
+    if verdict.is_anomaly:
+        marker = f"{_RED}\u26a0 ANOMALY{_RESET}" if color else "! ANOMALY"
+        # A new WARN shape can flag a window that holds zero errors \u2014
+        # show the warn count too, or the header reads "errors: 0" with
+        # no hint of what actually tripped the detector.
+        counts = f"errors: {window.error_count}"
+        if window.warn_count:
+            counts += f"  warns: {window.warn_count}"
+        header = (
+            f"  {label}  {marker}  {counts}  "
+            f"baseline: ~{verdict.baseline_mean:.1f}"
+            + (f"   score: {verdict.error_score:.1f}x" if verdict.error_score else "")
+        )
+        lines = [header]
+        levels = _shape_levels(window)
+        for shape in verdict.new_shapes:
+            kind = _signature_label(levels.get(shape, "ERROR"))
+            note = f"    New {kind} signature detected: {shape!r}"
+            lines.append(f"{_YELLOW}{note}{_RESET}" if color else note)
+        if not verdict.new_shapes and not explanation:
+            lines.append("    (error rate spike \u2014 no brand-new error signature)")
+        if explanation:
+            note = f"    Explanation: {explanation}"
+            lines.append(f"{_CYAN}{note}{_RESET}" if color else note)
+        return "\n".join(lines)
+    else:
+        text = f"  {label}  ok        errors: {window.error_count}   baseline: ~{verdict.baseline_mean:.1f}"
+        return f"{_DIM}{text}{_RESET}" if color else text
+
+
+def _format_json(window: Window, verdict: AnomalyVerdict, explanation: str | None = None) -> str:
+    payload = {
+        "window_index": window.index,
+        "start": window.start_label,
+        "end": window.end_label,
+        "error_count": window.error_count,
+        "warn_count": window.warn_count,
+        "baseline_mean": round(verdict.baseline_mean, 3),
+        "error_score": round(verdict.error_score, 3),
+        "is_anomaly": verdict.is_anomaly,
+        "new_shapes": verdict.new_shapes,
+        "explanation": explanation,
+    }
+    return json.dumps(payload)
+
+
+def run_tail(
+    source: Iterator[str | None],
+    window_seconds: float,
+    sensitivity: str,
+    output_format: str,
+    quiet: bool,
+    explain: bool = False,
+    explain_provider: str = "anthropic",
+    explain_model: str | None = None,
+    use_rich: bool = False,
+    ignore: list[Pattern[str]] | None = None,
+    out: TextIO = sys.stdout,
+) -> int:
+    """Core loop shared by file/stdin, replay/live. Returns an exit code."""
+    aggregator = WindowAggregator(window_seconds=window_seconds)
+    detector = AnomalyDetector(sensitivity=sensitivity)
+    color = output_format == "plain" and _supports_color(out)
+    anomaly_count = 0
+    window_count = 0
+    explain_warned = False  # only print an --explain setup problem once, not per-anomaly
+
+    console = None
+    if use_rich and output_format == "plain" and HAS_RICH and _supports_color(out):
+        from rich.console import Console
+        console = Console(file=out)
+
+    def get_explanation(window: Window) -> str | None:
+        nonlocal explain_warned
+        if not explain:
+            return None
+        try:
+            raw_lines = [l.raw for l in window.lines if l.level in ("ERROR", "WARN")]
+            return explain_window(raw_lines or [l.raw for l in window.lines], provider=explain_provider, model=explain_model)
+        except ExplainError as e:
+            if not explain_warned:
+                print(f"[logometer] --explain unavailable: {e}", file=sys.stderr)
+                explain_warned = True
+            return None
+
+    def handle(window: Window) -> None:
+        nonlocal anomaly_count, window_count
+        if not window.lines:
+            return
+        window_count += 1
+        verdict = detector.evaluate(window)
+        if verdict.is_anomaly:
+            anomaly_count += 1
+        if quiet and not verdict.is_anomaly:
+            return
+
+        explanation = get_explanation(window) if verdict.is_anomaly else None
+
+        if output_format == "json":
+            print(_format_json(window, verdict, explanation), file=out)
+        elif console is not None:
+            from .pretty import render_window
+            render_window(window, verdict, explanation, console)
+        else:
+            print(_format_plain(window, verdict, color, explanation), file=out)
+            print(file=out)
+
+        # Python block-buffers stdout when it isn't a terminal, so without
+        # this an alert can sit in memory for minutes when the output is
+        # redirected to a file or piped into something else — the exact
+        # setups a monitoring tool actually runs in.
+        _flush(out)
+
+    try:
+        for raw_line in source:
+            if raw_line is None:
+                # idle tick from a live source: close anything overdue
+                for window in aggregator.tick():
+                    handle(window)
+                continue
+            if ignore and any(p.search(raw_line) for p in ignore):
+                continue
+            for window in aggregator.feed(raw_line):
+                handle(window)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        for window in aggregator.flush():
+            handle(window)
+
+    if output_format != "json":
+        summary = f"-- {window_count} window(s) processed, {anomaly_count} anomaly(ies) flagged --"
+        if console is not None:
+            console.print(summary, style="dim")
+        else:
+            print(summary, file=out)
+        _flush(out)
+
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="logometer",
+        description="Tail your logs. Catch anomalies. Skip the 2am grep.",
+    )
+    parser.add_argument("--version", action="version", version=f"logometer {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    tail_parser = subparsers.add_parser("tail", help="Tail a log file (or stdin) and flag anomalous windows")
+    tail_parser.add_argument(
+        "file",
+        help="Path to a log file, or '-' to read from stdin",
+    )
+    tail_parser.add_argument(
+        "--window",
+        type=float,
+        default=10.0,
+        metavar="SECONDS",
+        help="Window size in seconds when timestamps are parseable (default: 10)",
+    )
+    tail_parser.add_argument(
+        "--sensitivity",
+        choices=["low", "medium", "high"],
+        default="medium",
+        help="How aggressively to flag deviations (default: medium)",
+    )
+    tail_parser.add_argument(
+        "--format",
+        choices=["plain", "json"],
+        default="plain",
+        dest="output_format",
+        help="Output format (default: plain)",
+    )
+    tail_parser.add_argument(
+        "--replay",
+        action="store_true",
+        help="Read a file from start to end and exit, instead of live-tailing it",
+    )
+    tail_parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only print anomalous windows, suppress 'ok' windows",
+    )
+    tail_parser.add_argument(
+        "--ignore",
+        action="append",
+        default=None,
+        metavar="REGEX",
+        dest="ignore",
+        help="Drop lines matching this regex before any analysis — use it to mute "
+             "known-noisy messages that would otherwise dominate the baseline. "
+             "Repeatable: --ignore 'healthcheck' --ignore 'DeprecationWarning'",
+    )
+    tail_parser.add_argument(
+        "--explain",
+        action="store_true",
+        help="Ask an LLM for a one-sentence explanation of each anomaly "
+             "(requires ANTHROPIC_API_KEY, OPENAI_API_KEY or OPENROUTER_API_KEY; fails soft if unset)",
+    )
+    tail_parser.add_argument(
+        "--explain-provider",
+        choices=["anthropic", "openai", "openrouter"],
+        default="anthropic",
+        help="Which API to use for --explain (default: anthropic)",
+    )
+    tail_parser.add_argument(
+        "--explain-model",
+        default=None,
+        metavar="MODEL",
+        help="Override the default model used for --explain",
+    )
+    tail_parser.add_argument(
+        "--no-pretty",
+        action="store_true",
+        help="Disable rich-styled output even if the 'rich' package is installed",
+    )
+
+    return parser
+
+
+def _raise_keyboard_interrupt(signum, frame):
+    raise KeyboardInterrupt()
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Treat SIGTERM the same as Ctrl-C (SIGINT) so a live-tailing process
+    # shuts down cleanly (flushing its in-progress window) whether it's
+    # interrupted at the terminal or killed by a process manager/`timeout`.
+    signal.signal(signal.SIGTERM, _raise_keyboard_interrupt)
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "tail":
+        ignore = []
+        for raw_pattern in args.ignore or []:
+            try:
+                ignore.append(re.compile(raw_pattern))
+            except re.error as e:
+                parser.error(f"invalid --ignore regex {raw_pattern!r}: {e}")
+
+        if args.file == "-":
+            source = _iter_stdin()
+        else:
+            # Check readability up front so a typo'd path produces one clear
+            # line instead of a traceback out of the middle of a generator.
+            if not os.path.exists(args.file):
+                print(f"[logometer] no such file: {args.file}", file=sys.stderr)
+                return 2
+            if os.path.isdir(args.file):
+                print(f"[logometer] {args.file} is a directory, not a log file", file=sys.stderr)
+                return 2
+            try:
+                open(args.file, "rb").close()
+            except OSError as e:
+                print(f"[logometer] cannot read {args.file}: {e.strerror}", file=sys.stderr)
+                return 2
+            source = _iter_file_replay(args.file) if args.replay else _iter_file_live(args.file)
+
+        try:
+            return run_tail(
+                source=source,
+                window_seconds=args.window,
+                sensitivity=args.sensitivity,
+                output_format=args.output_format,
+                quiet=args.quiet,
+                explain=args.explain,
+                explain_provider=args.explain_provider,
+                explain_model=args.explain_model,
+                use_rich=not args.no_pretty,
+                ignore=ignore,
+            )
+        except OSError as e:
+            # e.g. the file is deleted for good while we're live-tailing it
+            print(f"[logometer] stopped reading {args.file}: {e}", file=sys.stderr)
+            return 1
+
+    parser.error(f"unknown command {args.command!r}")
+    return 2
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except BrokenPipeError:
+        # e.g. piped into `head` — exit quietly instead of a traceback
+        sys.stderr.close()
+        sys.exit(0)

logometer/detector.py

@@ -0,0 +1,70 @@
+"""
+Turns a stream of Windows into a stream of (Window, AnomalyVerdict) pairs.
+
+A window is flagged anomalous if either:
+  (a) its error count deviates from the rolling baseline by more than
+      `sensitivity` standard deviations, or
+  (b) it contains an error "shape" that has never been seen before in
+      this run (and we're past the warm-up period).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .baseline import RollingBaseline
+from .windower import Window
+
+SENSITIVITY_MULTIPLIERS = {
+    "low": 3.0,      # only flag big, obvious spikes
+    "medium": 2.0,   # default
+    "high": 1.2,     # flag smaller deviations too — noisier
+}
+
+
+@dataclass
+class AnomalyVerdict:
+    is_anomaly: bool
+    error_score: float          # std-devs above baseline (0 if not ready/not anomalous)
+    new_shapes: list[str] = field(default_factory=list)
+    baseline_mean: float = 0.0
+
+
+class AnomalyDetector:
+    def __init__(self, sensitivity: str = "medium", history_size: int = 20):
+        """Configure spike threshold (low/medium/high) and rolling error-count baseline.
+        Also initializes the set of error shapes seen so far in this run."""
+        if sensitivity not in SENSITIVITY_MULTIPLIERS:
+            raise ValueError(f"unknown sensitivity {sensitivity!r}, expected one of {list(SENSITIVITY_MULTIPLIERS)}")
+        self.multiplier = SENSITIVITY_MULTIPLIERS[sensitivity]
+        self._error_baseline = RollingBaseline(history_size=history_size)
+        self._seen_shapes: set[str] = set()
+        self._warmed_up = False  # true once we've built at least one baseline observation
+
+    def evaluate(self, window: Window) -> AnomalyVerdict:
+        """Score one window for error spikes and unseen error shapes; update baseline state.
+        Volume spikes are omitted from baseline updates; new shapes still learn normal volume."""
+        error_count = window.error_count
+        score = self._error_baseline.deviation_score(error_count)
+        score_anomaly = self._error_baseline.ready and score >= self.multiplier
+
+        new_shapes = []
+        if self._warmed_up:
+            for shape in window.shapes:
+                if shape not in self._seen_shapes:
+                    new_shapes.append(shape)
+
+        for shape in window.shapes:
+            self._seen_shapes.add(shape)
+
+        verdict = AnomalyVerdict(
+            is_anomaly=bool(score_anomaly or new_shapes),
+            error_score=score if score != float("inf") else 999.0,
+            new_shapes=new_shapes,
+            baseline_mean=self._error_baseline.mean,
+        )
+
+        if not score_anomaly:
+            self._error_baseline.update(error_count)
+        self._warmed_up = True
+
+        return verdict