What is logaround?

Log files: love them, hate them, definitely need them—especially when the pager beeps at 3AM. I used a custom shell function to dig up context around weird log entries with journalctl. It worked, but had limits.

So I rewrote logaround in Python.

The result:

  • Color highlights
  • Human-friendly time filters
  • True context windows (before/after)
  • Never loses lines, even with messy logs
  • Pandas-powered for hacking and export

TL;DR:
You can finally say:

“Show me everything that happened around this error at 9:14pm yesterday—and don’t make me lose the plot!”

Quick Start

🔗 View logaround on GitHub

Clone from GitHub:

git clone https://github.com/forfaxx/logaround.git
cd logaround
chmod +x logaround.py

Create a virtual environment and activate it:

python3 -m venv venv
source venv/bin/activate

Install dependencies

pip install -r requirements.txt

or 

pip install pandas rich

You should now be ready to go. For a really handy way to automate activating and deactivating the venv, see the following: Optional and advanced

Features

  • Search by time or text: Jump to events or messages anywhere in your logs.
  • Delta/context: See lines before and after each match—like grep -A/-B, but smarter.
  • Highlighting: Instantly see what matched, even in noisy logs.
  • Human time: Use "last Friday 11pm", "2 hours ago", "yesterday 14:00"—anything GNU date understands.
  • No dropped lines: Even logs with weird or unmatched formats are shown.
  • Hackable: Everything loads into a pandas DataFrame for analysis or export.

Usage

./logaround.py --term network --delta 5 --since "yesterday 12:00"
./logaround.py --term apt --since "last week" --max 30
./logaround.py --since "2024-07-28 16:00" --until "2024-07-28 18:00" --term failed --delta 8
./logaround.py --help

Main options:

  • --term STR Search for this term (repeat for AND-search)
  • --delta N Show ±N context lines around matches
  • --since TIME Start time (any GNU date-friendly string)
  • --until TIME End time (same as above)
  • --lines N How many log lines to fetch if not filtering by time (default: 500)
  • --max N Max number of results to show (default: 100)
  • -h, --help Show help message and exit
  • -v, --version Show version and exit

Screenshot

logaround search demo

Supported Timestamps

You can use any date/time string GNU date will parse:

  • "2025-07-30 13:41:12"
  • "yesterday 22:00"
  • "last Friday 17:30"
  • "now", "midnight", "tomorrow"
  • "1 week ago", "next Tuesday"

See man date or the
GNU date documentation
for all supported formats.

Mac users will need to install GNU coreutils if you want fuzzy time formats.

If your timestamp can’t be parsed, logaround just falls back to loading logs without time filters—no drama.

Supercharging Your Logs With logger

Want to bookmark key moments or tests?
Use the built-in logger tool:

logger "logaround demo: starting nginx stress test"
./logaround.py --term demo --delta 10

You’ll see your custom log entries, with full context.
Perfect for reproducible bug hunts or marking long troubleshooting sessions.

Why Move to Python?

My original bash function worked for quick-and-dirty context—but it was hard to maintain, extend, or customize (and you couldn’t highlight matches in color!). With Python I have greater control over the data and can do all sorts of nice things like:

  • Safely parse every log line (or gracefully handle ones that don’t match)
  • Highlight what matters
  • Build new features—like advanced filtering, export, or compound logic

Future Directions

  • Support for macOS (asl)
  • Compound and OR/NOT searches
  • CSV export, better output options
  • Smarter highlighting and error detection

Got a feature wish? Email me, or submit a PR!

Requirements

  • Python 3.8+
  • pandas, rich
  • journalctl (systemd-based systems)
  • GNU date (for flexible time parsing; default on most Linux distros)

License

MIT

Conclusion

That’s it! Find log events like a pro with logaround.py

Have a tweak, found a bug, or want to share your own logaround wizardry?
Email me!

Happy hacking—and may all your outages be short.