awatch 1.0.0

Terminal TUI dashboard for real-time log monitoring

awatch 🖥️

A Watchful Terminal Analytics for Continuous Hosting 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

pip install awatch

---

Usage

# 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

# 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 for details.

---

Author

Built by Ashish — github.com/ashishnxt