Session tracking, simplified. A command-line tool that reads user login/logout event logs and reports who was on which machine, when, and for how long.
- Full session history and a live "who's online right now" view
- Filter sessions by user or by date
- Export reports to CSV or JSON
- Handles messy real-world logs without crashing -- duplicate logins, orphan logouts, unclosed sessions, malformed lines, and unsorted files are all detected and handled gracefully
- Usernames are case-insensitive
- Styled terminal output with a cyan-to-green gradient banner (rich + pyfiglet)
Help screen
Full session report
Live view (currently active sessions)
SessionLedger uses a strict layered architecture -- the business logic has zero knowledge of files, the terminal, or argparse:
Log file --> EventParser --> SessionTracker --> Reporter --> CLI (rich output) (I/O only)(pure logic,(formatting zero I/O)only)
This separation is what makes the core logic reusable at any scale. SessionTracker doesn't know or care whether events came from a static log file, a live feed, or a message queue like Kafka across 1,000s of machines -- only the I/O layer feeding it would change, not the tracking logic itself.
git clone https://github.com/Aayush29052006/Session-Ledger.git
cd Session-Ledger
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txtShow the help screen:
python -m sessionledger.cli --helpFull session history:
python -m sessionledger.cli --log sample_logs/sample_events.csvOnly currently active sessions:
python -m sessionledger.cli --log sample_logs/sample_events.csv --liveFilter by user:
python -m sessionledger.cli --log sample_logs/sample_events.csv --user aliceFilter by date:
python -m sessionledger.cli --log sample_logs/sample_events.csv --date 2026-07-14Export to CSV or JSON:
python -m sessionledger.cli --log sample_logs/sample_events.csv --export csv
python -m sessionledger.cli --log sample_logs/sample_events.csv --export jsonPlain CSV, one event per line, no header row:
timestamp,machine,user,event_type 2026-07-14 08:03:12,server1,alice,login 2026-07-14 08:41:07,server1,alice,logout
| Case | Behavior |
|---|---|
| Duplicate login | Warning logged, first login time kept |
| Orphan logout (no matching login) | Warning logged, event skipped |
| Session with no logout | Marked as "active" |
| Malformed / corrupted line | Warning logged, line skipped |
| Unknown event type | Warning logged, line skipped |
| Unsorted log file | Automatically sorted by timestamp before processing |
| Empty log file | "No sessions found" message, no crash |
| Case differences in usernames | Treated as the same user |
Full test matrix in tests/TEST_PLAN.md.
python -m pytest -v27 tests covering the parser, tracker, and reporter layers.
- Python 3
- rich -- styled terminal output
- pyfiglet -- ASCII art banner
- pytest -- testing
Built as a portfolio project following a structured 14-step development process: problem definition, architecture design, edge-case planning, bottom-up implementation with tests alongside every feature, and documentation.
Aayush Jivan Chaudhari