loggrepper 0.1.0__py3-none-any.whl

loggrepper/cli.py

@@ -0,0 +1,77 @@
+from datetime import datetime, timedelta
+from re import compile
+
+import click
+
+from loggrepper.models import LogLine
+from loggrepper.timestamp import BUILTIN_FORMATS, detect_format, extract_timestamp
+from loggrepper.grouper import group_incidents
+from loggrepper.formatter import get_formatter
+
+
+@click.command()
+@click.argument("pattern")
+@click.argument("file", type=click.Path(exists=True))
+@click.option("--window", "-w", default=3, help="Ventana en segundos alrededor del match")
+@click.option("--ts-format", default="auto", help="Formato de timestamp (auto, iso8601, syslog, nginx, epoch-ms)")
+@click.option("--output", "-o", default="pretty", type=click.Choice(["pretty", "json"]), help="Formato de salida")
+def main(pattern: str, file: str, window: int, ts_format: str, output: str) -> None:
+    """Extrae ventanas de contexto alrededor de matches en archivos de log.
+
+    Ejemplo: loggrepper ERROR app.log -w 5 --output json
+    """
+    # ── formato de timestamp ──────────────────────────────────────
+    if ts_format == "auto":
+        with open(file) as f:
+            head = [next(f, "").rstrip("\n") for _ in range(50)]
+            head = [l for l in head if l]
+        fmt = detect_format(head)
+        if fmt is None:
+            raise click.UsageError(
+                "No se pudo detectar el formato de timestamp. "
+                "Usa --ts-format para especificar uno (iso8601, syslog, nginx, epoch-ms)."
+            )
+        click.echo(f"Formato detectado: {fmt.name}", err=True)
+    else:
+        fmt = BUILTIN_FORMATS.get(ts_format)
+        if fmt is None:
+            valid = ", ".join(BUILTIN_FORMATS.keys())
+            raise click.BadParameter(f"Formato '{ts_format}' desconocido. Opciones: {valid}")
+
+    # ── compilar patron de busqueda ───────────────────────────────
+    try:
+        pat = compile(pattern)
+    except Exception as e:
+        raise click.BadParameter(f"Patron regex invalido: {e}")
+
+    window_td = timedelta(seconds=window)
+    formatter = get_formatter(output)
+
+    # ── procesar archivo ──────────────────────────────────────────
+    with open(file) as f:
+        raw_lines = (
+            LogLine(number=i, raw=line.rstrip("\n"))
+            for i, line in enumerate(f, 1)
+        )
+
+        timestamped: list[tuple[LogLine, datetime, bool]] = []
+        skipped = 0
+        for logline in raw_lines:
+            ts = extract_timestamp(logline.raw, [fmt])
+            if ts is None:
+                skipped += 1
+                continue
+            matched = pat.search(logline.raw) is not None
+            timestamped.append((logline, ts, matched))
+
+    if skipped:
+        click.echo(f"Lineas sin timestamp detectado: {skipped}", err=True)
+
+    # ── agrupar y mostrar ─────────────────────────────────────────
+    incidents = list(group_incidents(iter(timestamped), window_td))
+
+    if not incidents:
+        click.echo(formatter.format([]))
+        return
+
+    click.echo(formatter.format(incidents))

loggrepper/formatter.py

@@ -0,0 +1,66 @@
+"""Formateadores de output para incidentes."""
+import json
+from typing import Protocol
+
+from loggrepper.models import Incident
+
+
+class Formatter(Protocol):
+    """Protocolo que todo formateador debe cumplir."""
+    def format(self, incidents: list[Incident]) -> str:
+        ...
+
+
+class PrettyFormatter:
+    """Output legible para humanos, con colores y marcadores."""
+
+    def format(self, incidents: list[Incident]) -> str:
+        if not incidents:
+            return "Sin incidentes encontrados."
+
+        lines: list[str] = []
+        for inc in incidents:
+            lines.append(
+                f"--- Incidente #{inc.id} | "
+                f"{inc.start} — {inc.end} | "
+                f"{len(inc.lines)} lineas ---"
+            )
+            for i, logline in enumerate(inc.lines):
+                marker = ">>>" if i in inc.matches else "   "
+                lines.append(f"{marker} {logline.raw}")
+            lines.append("")
+        return "\n".join(lines)
+
+
+class JsonFormatter:
+    """Output JSON, ideal para pipe a jq u otras herramientas."""
+
+    def format(self, incidents: list[Incident]) -> str:
+        data = [
+            {
+                "id": inc.id,
+                "start": inc.start.isoformat(),
+                "end": inc.end.isoformat(),
+                "line_count": len(inc.lines),
+                "match_count": len(inc.matches),
+                "lines": [
+                    {
+                        "number": logline.number,
+                        "text": logline.raw,
+                        "match": i in inc.matches,
+                    }
+                    for i, logline in enumerate(inc.lines)
+                ],
+            }
+            for inc in incidents
+        ]
+        return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+def get_formatter(output: str) -> Formatter:
+    """Devuelve el formateador segun el formato elegido."""
+    formatters: dict[str, Formatter] = {
+        "pretty": PrettyFormatter(),
+        "json": JsonFormatter(),
+    }
+    return formatters[output]

loggrepper/grouper.py

@@ -0,0 +1,80 @@
+from datetime import datetime, timedelta
+from collections.abc import Iterator
+
+from loggrepper.models import Incident, LogLine
+
+
+def group_incidents(
+    items: Iterator[tuple[LogLine, datetime, bool]],
+    window: timedelta,
+) -> Iterator[Incident]:
+    incident: Incident | None = None
+    next_id = 1
+    pending: list[tuple[LogLine, datetime]] = []
+
+    for line, ts, matched in items:
+        if incident is not None and ts <= incident.end:
+            incident.lines.append(line)
+            if matched:
+                incident.matches.append(len(incident.lines) - 1)
+                incident.end = max(incident.end, ts + window)
+            continue
+
+        if incident is not None and ts > incident.end:
+            yield incident
+            pending = _discard_before(pending, incident.end)
+            incident = None
+            # la linea actual se reprocesa en el siguiente if
+
+        if incident is None:
+            if matched:
+                incident = _new_incident(next_id, line, ts, window, pending)
+                next_id += 1
+            else:
+                pending.append((line, ts))
+
+    if incident is not None:
+        yield incident
+
+
+def _new_incident(
+    iid: int,
+    match_line: LogLine,
+    match_ts: datetime,
+    window: timedelta,
+    pending: list[tuple[LogLine, datetime]],
+) -> Incident:
+    """Crea incidente rescatando lineas pendientes dentro de [match_ts - window, ...]."""
+    start = match_ts - window
+    incident_lines: list[LogLine] = []
+    incident_matches: list[int] = []
+
+    # rescatar lineas pendientes dentro de la ventana
+    survivors: list[tuple[LogLine, datetime]] = []
+    for pl, pts in pending:
+        if pts >= start:
+            incident_lines.append(pl)
+        else:
+            survivors.append((pl, pts))
+
+    pending.clear()
+    pending.extend(survivors)
+
+    incident_matches.append(len(incident_lines))
+    incident_lines.append(match_line)
+
+    return Incident(
+        id=iid,
+        start=start,
+        end=match_ts + window,
+        lines=incident_lines,
+        matches=incident_matches,
+    )
+
+
+def _discard_before(
+    pending: list[tuple[LogLine, datetime]],
+    cutoff: datetime,
+) -> list[tuple[LogLine, datetime]]:
+    """Descarta lineas con timestamp <= cutoff."""
+    return [(pl, pts) for pl, pts in pending if pts > cutoff]

loggrepper/matcher.py

@@ -0,0 +1,9 @@
+from re import Pattern
+from collections.abc import Iterator
+
+from loggrepper.models import LogLine
+
+def match_lines(lines: Iterator[LogLine], patterns: list[Pattern]) -> Iterator[tuple[LogLine, bool]]:
+    for line in lines:
+        matched = any(p.search(line.raw) for p in patterns)
+        yield line, matched 

loggrepper/models.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+@dataclass
+class LogLine:
+    number: int
+    raw: str
+
+@dataclass
+class Incident:
+    id: int
+    start: datetime
+    end: datetime
+    lines: list[LogLine]
+    matches: list[int]
+

loggrepper/timestamp.py

@@ -0,0 +1,90 @@
+from datetime import datetime
+from re import Pattern, compile
+from typing import Literal
+from dataclasses import dataclass
+
+
+@dataclass
+class TimestampFormat:
+    """Define como extraer y parsear un timestamp de una linea."""
+    name: str
+    regex: Pattern
+    format_str: str
+    position: Literal["start", "anywhere"]
+
+
+def extract_timestamp(line: str, formats: list[TimestampFormat]) -> datetime | None:
+    """Prueba cada formato contra la linea, devuelve el primer datetime parseado."""
+    for fmt in formats:
+        match = fmt.regex.match(line) if fmt.position == "start" else fmt.regex.search(line)
+        if match:
+            ts_str = match.group(0)
+            if fmt.name == "epoch-ms":
+                try:
+                    return datetime.fromtimestamp(int(ts_str) / 1000)
+                except (ValueError, OSError):
+                    continue
+            try:
+                return datetime.strptime(ts_str, fmt.format_str)
+            except ValueError:
+                continue
+    return None
+
+
+def detect_format(lines: list[str]) -> TimestampFormat | None:
+    """Auto-detecta el formato de timestamp analizando las primeras lineas."""
+    best: tuple[TimestampFormat, int] | None = None
+    for fmt in ALL_FORMATS:
+        hits = sum(1 for line in lines if extract_timestamp(line, [fmt]) is not None)
+        if hits > len(lines) * 0.5:
+            if best is None or hits > best[1]:
+                best = (fmt, hits)
+    return best[0] if best else None
+
+
+# ── Formatos predefinidos ────────────────────────────────────────────
+
+ISO8601 = TimestampFormat(
+    name="iso8601",
+    regex=compile(r"\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d{3,6})?(?:[+-]\d{2}:?\d{2}|Z)?"),
+    format_str="%Y-%m-%d %H:%M:%S.%f",
+    position="anywhere",
+)
+
+ISO8601_T = TimestampFormat(
+    name="iso8601-t",
+    regex=compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3,6})?(?:[+-]\d{2}:?\d{2}|Z)?"),
+    format_str="%Y-%m-%dT%H:%M:%S.%f",
+    position="anywhere",
+)
+
+SYSLOG = TimestampFormat(
+    name="syslog",
+    regex=compile(r"[A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2}"),
+    format_str="%b %d %H:%M:%S",
+    position="anywhere",
+)
+
+NGINX = TimestampFormat(
+    name="nginx",
+    regex=compile(r"\d{2}/[A-Z][a-z]{2}/\d{4}:\d{2}:\d{2}:\d{2} [+-]\d{4}"),
+    format_str="%d/%b/%Y:%H:%M:%S %z",
+    position="anywhere",
+)
+
+EPOCH_MS = TimestampFormat(
+    name="epoch-ms",
+    regex=compile(r"\b\d{13}\b"),
+    format_str="",
+    position="anywhere",
+)
+
+BUILTIN_FORMATS: dict[str, TimestampFormat] = {
+    "iso8601": ISO8601,
+    "iso8601-t": ISO8601_T,
+    "syslog": SYSLOG,
+    "nginx": NGINX,
+    "epoch-ms": EPOCH_MS,
+}
+
+ALL_FORMATS: list[TimestampFormat] = list(BUILTIN_FORMATS.values())

loggrepper-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: loggrepper
+Version: 0.1.0
+Summary: grep contextual para logs con ventanas de tiempo
+Author-email: Matias Atuan <matiasatuan.2018@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/FixZzT/loggrepper
+Project-URL: Repository, https://github.com/FixZzT/loggrepper
+Project-URL: Issues, https://github.com/FixZzT/loggrepper/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8
+Requires-Dist: rich>=13
+Dynamic: license-file
+
+# loggrepper
+
+[![CI](https://github.com/FixZzT/loggrepper/actions/workflows/ci.yml/badge.svg)](https://github.com/FixZzT/loggrepper/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/loggrepper.svg)](https://pypi.org/project/loggrepper/)
+[![PyPI](https://img.shields.io/pypi/v/loggrepper.svg)](https://pypi.org/project/loggrepper/)
+[![License](https://img.shields.io/github/license/FixZzT/loggrepper.svg)](https://github.com/FixZzT/loggrepper/blob/master/LICENSE)
+
+grep contextual para logs. Extrae ventanas de tiempo alrededor de matches en archivos de log — no por número de líneas, sino por timestamps.
+
+## El problema
+
+`grep ERROR app.log` te da esto:
+
+```
+2026-05-16 14:32:01.123 ERROR PaymentProcessor: timeout
+```
+
+Pero no te dice **qué pasó antes** del error (¿llegó el request? ¿qué parámetros tenía?) ni **después** (¿se reintentó? ¿el usuario recibió 500?).
+
+`grep -B 20 -A 20` asume que 20 líneas cubren tu ventana de tiempo. Si el request empezó 2 segundos antes y tu log es verboso, 20 líneas puede ser muy poco. Si es poco verboso, 20 líneas es ruido innecesario.
+
+**loggrepper** busca por timestamps reales. Le pasas `--window 3s` y te devuelve todas las líneas cuyo timestamp está dentro de ±3 segundos del match. Líneas sueltas se agrupan en "incidentes". Ventanas solapadas se fusionan.
+
+## Instalación
+
+```bash
+pip install git+https://github.com/FixZzT/loggrepper.git
+# o modo desarrollo (editable)
+pip install -e .
+# o global con pipx
+pipx install git+https://github.com/FixZzT/loggrepper.git
+```
+
+## Uso
+
+```bash
+# Básico
+loggrepper ERROR app.log
+
+# Ventana de 5 segundos
+loggrepper ERROR app.log -w 5
+
+# Salida JSON para scripts
+loggrepper ERROR app.log -o json | jq '.[] | {start, end, line_count}'
+
+# Formato de timestamp específico
+loggrepper "404" nginx-access.log --ts-format nginx
+
+# Pipe desde docker/k8s
+docker logs mi-app 2>&1 | loggrepper FATAL -
+kubectl logs pod-xyz | loggrepper panic -
+```
+
+## Ejemplos reales
+
+**Depurar un error en producción:**
+
+```bash
+$ loggrepper "IntegrityError" app.log -w 5
+
+--- Incidente #1 | 14:32:00 — 14:32:04 | 5 líneas ---
+    14:32:00.100 INFO  POST /api/orders payload={"user":42}
+    14:32:00.500 DEBUG INSERT INTO orders VALUES (...)
+>>> 14:32:01.123 ERROR IntegrityError: duplicate key
+    14:32:01.200 WARN  rolling back transaction
+    14:32:02.000 INFO  POST /api/orders -> 500
+```
+
+Ves el request entero, SQL, error, rollback, y respuesta — en contexto temporal real.
+
+**Investigar timeouts entre microservicios:**
+
+```bash
+$ loggrepper "pi_abc123" payment-service.log -w 10
+
+--- Incidente #1 | 14:32:00 — 14:32:10 | 7 líneas ---
+    14:32:00.100 INFO  received payment intent pi_abc123
+    14:32:00.200 DEBUG calling Stripe /v1/payment_intents
+>>> 14:32:08.500 ERROR timeout calling Stripe (8.3s)
+    14:32:08.501 WARN  retrying (1/3)
+    14:32:10.000 DEBUG Stripe responded 200 OK
+```
+
+Stripe tardó 8s, no es tu código. La ventana captura causa y efecto.
+
+**Auditar requests sospechosos en nginx:**
+
+```bash
+$ loggrepper "POST /admin" access.log --ts-format nginx -w 30 -o json | jq .
+```
+
+## Formatos de timestamp soportados
+
+| Formato   | Ejemplo                                    | Uso típico              |
+|-----------|--------------------------------------------|--------------------------|
+| iso8601   | `2026-05-16 14:32:01.123 ERROR`            | Python, Java, Node, Go   |
+| iso8601-t | `2026-05-16T14:32:01.123Z ERROR`           | JSON logs, Docker, k8s   |
+| syslog    | `May 16 14:32:01 hostname error:`          | syslog, journald, /var/log |
+| nginx     | `16/May/2026:14:32:01 +0000 GET /`         | Nginx, Apache access     |
+| epoch-ms  | `1715872321123 ERROR`                      | Splunk, sistemas embedded |
+
+Con `--ts-format auto` (default) detecta automáticamente el formato analizando las primeras 50 líneas.
+
+## Output
+
+**Pretty** (default):
+
+```
+--- Incidente #1 | 2026-05-16 14:31:58 — 2026-05-16 14:32:04 | 5 líneas ---
+    2026-05-16 14:32:00.100 INFO  inicio del proceso
+>>> 2026-05-16 14:32:01.123 ERROR timeout en conexión
+    2026-05-16 14:32:02.000 DEBUG conexión exitosa
+```
+
+`>>>` marca las líneas que coinciden con el patrón. Cada incidente muestra rango temporal y cantidad de líneas.
+
+**JSON**: cada incidente con id, start, end, líneas con número, texto y flag `match`.
+
+## Desarrollo
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+pytest            # 14 tests
+ruff check src/ tests/
+```

loggrepper-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+loggrepper/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+loggrepper/cli.py,sha256=DcWXbe0TUm3CEYVf_dJhkU2mBClImOGlsfgVTfKB74k,3276
+loggrepper/formatter.py,sha256=83S62Qv6IwRKq-evbdBwFBaPu59Yzoy6BtHnNwF_Loc,2036
+loggrepper/grouper.py,sha256=BBLS5dB0CSqkQp63r9lc8scKBoZYJTyTTla_Ijo3RU8,2319
+loggrepper/matcher.py,sha256=h6UyJC2foY5G3EpLjk-sFIy8RmkqvA-Gb8jBf3JF8bM,313
+loggrepper/models.py,sha256=2JhoXp213oOy9WBWJbteRRwzymrOPsjUH8XAlMlitm4,247
+loggrepper/timestamp.py,sha256=Kglf7jWiSz9kmFOpNGCVR5mR4AW8iSCyPTxvKaquT2o,2808
+loggrepper-0.1.0.dist-info/licenses/LICENSE,sha256=SdnvK8jBdHqrqVuIZVe5lutHvymf56Lr7nGP3FZ5uXg,1069
+loggrepper-0.1.0.dist-info/METADATA,sha256=syOVQvtIYafKVt3vR_rmu--dk1osVDJoY0E3Qol4yyI,5036
+loggrepper-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+loggrepper-0.1.0.dist-info/entry_points.txt,sha256=iqQVpYjIOs1inwrZ2sLaZICcb-2a-kZcPY303DLft7k,51
+loggrepper-0.1.0.dist-info/top_level.txt,sha256=PyYppPASup7reNEcmtMy7lzmrDc49zjw4HnzmYMpI7Y,11
+loggrepper-0.1.0.dist-info/RECORD,,

loggrepper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

loggrepper-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+loggrepper = loggrepper.cli:main

loggrepper-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matias Atuan
+
+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.

loggrepper-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+loggrepper