Metadata-Version: 2.4
Name: awatch
Version: 1.0.0
Summary: Terminal TUI dashboard for real-time log monitoring
Author-email: Ashish <your@email.com>
License: MIT License
        
        Copyright (c) 2026 Ashish
        
        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.
        
Project-URL: Homepage, https://github.com/ashishnxt/awatch
Project-URL: Repository, https://github.com/ashishnxt/awatch
Project-URL: Bug Tracker, https://github.com/ashishnxt/awatch/issues
Keywords: log,monitoring,tui,terminal,dashboard,syslog
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# awatch 🖥️

> **A** **W**atchful **T**erminal **A**nalytics for **C**ontinuous **H**osting logs

Real-time TUI (Terminal UI) log monitoring dashboard for Linux and macOS. Monitor any log file live — with severity filtering, text search, bar charts, and a scrollable detail view — all inside your terminal.

---

## Screenshot

```
╭──────────────────────────────────────────────────────────────────────────────────────╮
│ ╭─────────────────────────────────────────────────────────────────────────────────╮  │
│ │ STATUS: LIVE           LAST LOG: 2026-01-02T14:32:01       TIME: 2026-01-02 ... │  │
│ ╰─────────────────────────────────────────────────────────────────────────────────╯  │
│ ╭─ SYSTEM INFO ─────────────────────────╮  ╭─ CRITICAL ──╮  ╭─ WARNINGS ──╮        │
│ │ SYSTEM: prod-server-01   SIZE: 42.3MB │  │ Count: 2    │  │ Count: 14   │        │
│ │ TOTAL: 8432 | CRIT:2 ERR:11 WARN:14  │  │ |  |        │  │ | || |      │        │
│ │ Range: 2026-01-01 to 2026-01-02       │  ╰─────────────╯  ╰─────────────╯        │
│ ╰───────────────────────────────────────╯                                            │
│ ╭─ RECENT LOGS ──────────────────────── [Filtered: 120/8432] l:details | ↑↓:scroll ─╮│
│ │ [Jan  2 14:32:01] [CRIT] kernel: BIOS bug: ...                                    ││
│ │ [Jan  2 14:31:55] [ERR ] nginx: connect() failed (111: Connection refused)        ││
│ │ [Jan  2 14:31:40] [WARN] systemd: Unit ssh.service is degraded.                  ││
│ │ [Jan  2 14:31:22] [INFO] sshd[2341]: Accepted publickey for ashish               ││
│ ╰────────────────────────────────────────────────────────────────────────────────────╯│
╰──────────────────────────────────────────────────────────────────────────────────────╯
```

---

## Features

- **Live tail** — monitors any log file in real-time, handles file rotation and truncation automatically
- **Severity detection** — auto-classifies each line as `CRITICAL`, `ALERT`, `ERROR`, `WARN`, `INFO`, or `DEBUG` using regex pattern matching
- **Text search** — filter logs by any keyword with highlighted matches
- **Severity filter** — show only the severity level you care about
- **Bar charts** — live sparkline-style bar charts for CRITICAL, WARNINGS, ERRORS, and INFO counts (visible on wide terminals ≥ 130 cols)
- **Detail view** — full-width table with timestamp, severity, and message columns; searchable separately
- **Scroll** — scroll through history in both main and detail views
- **Date range** — shows the date range of logs currently loaded
- **File rotation handling** — detects truncation/rotation and re-opens the file automatically
- **No-limit mode** — load the entire log file instead of the default last 10,000 lines
- **Zero dependencies** — uses only Python stdlib (`curses`, `threading`, `re`, `collections`)

---

## Install

```bash
pip install awatch
```

---

## Usage

```bash
# Monitor default syslog
awatch

# Monitor a specific file
awatch /var/log/nginx/error.log
awatch /var/log/auth.log
awatch /var/log/postgresql/postgresql.log

# Load entire file (no 10,000 line cap)
awatch --no-limit
awatch /var/log/syslog --no-limit

# Check version
awatch -v
awatch --version
```

---

## Keybindings

### Main View

| Key | Action |
|-----|--------|
| `t` | Enter text search — type keyword, press `Enter` to apply |
| `v` | Filter by severity — type `ERROR`, `WARN`, `INFO`, `CRITICAL`, `DEBUG`, or `ALERT` |
| `c` | Clear all active filters |
| `l` | Open detail view (full table with all fields) |
| `r` | Reload — re-reads file from disk |
| `p` | Change log file path — type new path, press `Enter` |
| `↑` | Scroll up (older logs) |
| `↓` | Scroll down (newer logs) |
| `q` | Quit |
| `ESC` | Cancel current input |

### Detail View

| Key | Action |
|-----|--------|
| `s` | Search within detail view |
| `c` | Clear detail search |
| `↑` / `↓` | Scroll one line |
| `PgUp` / `PgDn` | Scroll ten lines |
| `ESC` or `b` | Back to main dashboard |
| `q` | Quit |

---

## Severity Levels

| Level | Color | Matches |
|-------|-------|---------|
| `CRITICAL` | 🔴 Red | `CRITICAL`, `CRIT`, `FATAL`, `EMERG`, `EMERGENCY` |
| `ALERT` | 🟣 Magenta | `ALERT` |
| `ERROR` | 🔴 Red | `ERROR`, `ERR`, `FAILURE`, `FAILED` |
| `WARN` | 🟡 Yellow | `WARN`, `WARNING` |
| `INFO` | 🔵 Cyan | `INFO`, `INFORMATION`, `NOTICE` |
| `DEBUG` | 🔷 Blue | `DEBUG`, `TRACE` |

---

## Supported Log Formats

awatch parses standard syslog format automatically:

```
Jan  2 14:32:01 hostname process[pid]: message
2026-01-02T14:32:01.123Z hostname process[pid]: message
```

Any line that doesn't match syslog format is still displayed — the full raw line is shown as the message. This means awatch works with any plain-text log file.

---

## Terminal Requirements

| Requirement | Minimum |
|-------------|---------|
| Terminal size | 80 × 30 |
| Terminal size (with graphs) | 130+ columns wide |
| OS | Linux, macOS |
| Python | 3.8+ |

---

## Performance

| Mode | Behavior |
|------|----------|
| Default | Reads last 2MB of file → keeps last 10,000 lines in memory |
| `--no-limit` | Reads entire file from start, no line cap |

New lines are polled every 50ms. Screen redraws are throttled to once per second minimum unless new data arrives.

---

## Common Log Files

```bash
# System
awatch /var/log/syslog
awatch /var/log/messages
awatch /var/log/kern.log

# Auth
awatch /var/log/auth.log
awatch /var/log/secure

# Web servers
awatch /var/log/nginx/error.log
awatch /var/log/nginx/access.log
awatch /var/log/apache2/error.log

# Database
awatch /var/log/postgresql/postgresql-16-main.log
awatch /var/log/mysql/error.log

# Application / Docker
awatch /var/log/myapp/app.log
awatch /var/lib/docker/containers/<id>/<id>-json.log
```

---

## Requirements

- Python 3.8 or higher
- Linux or macOS (Windows not supported — `curses` is unavailable)
- No third-party packages required

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

## Author

Built by **Ashish** — [github.com/ashishnxt](https://github.com/ashishnxt)
