CLOG is a specialised log processor and visualiser built in Go. It solves user JSON-squinting by transforming Caddy's structured logs into an interactive, human-centric dashboard. Designed for systems administrators and developers who need instant situational awareness without the overhead of heavy logging stacks.
Transforming messy, hard-to-read JSON streams into a clean, actionable visual interface.
- 🖥️ Auto-Height Matching: Dashboard mode automatically matches the height and width of your terminal window, even if you resize it!
- ⚡ Zero-Latency Streaming: Uses non-blocking I/O to handle high-traffic environments without dropping frames.
- 📊 Real-time Analytics: Instant status code distribution (2xx, 3xx, 4xx, 5xx) visualised in the TUI.
- 🔍 Power Filtering: Regex-based or field-specific filtering to isolate problematic endpoints or specific status codes.
- 👀 Schema Aware: Deep understanding of Caddy's default JSON log structure—no configuration required.
- 🎨 Responsive TUI: Built with a terminal UI that scales from small side-panes to full-screen NOC displays.
- ⬇️ Low CPU Overhead: Log parsing happens in parallel worker pools using Go routines.
- 🧠 Predictable Memory: Uses a fixed-size ring buffer for history to prevent memory leaks.
- 🏎️ Efficiency: Capable of processing thousands of lines per second with negligible latency.
Requires Go 1.24 or higher.
git clone https://github.com/hellotimking/clog.git
cd cloggo build -ldflags="-s -w" -o clog
sudo mv clog /usr/local/bin/
| Flag | Long Flag | Description |
|---|---|---|
| -l | --lines | Number of previous lines to show from the log file. |
| -h | --host | Only show logs for a specific domain or IP address. |
| -f | --find | Only show lines containing a specific string. |
| -e | --errors | Only show requests with status code >= 400. |
| -ha | --hide-assets | Hides common asset types (.js, .css, images, etc). |
| -aw | --assets-whitelist | Extensions to show that are normally hidden separated with comma, semi-colon, or pipe (.js,.json,.pdf). |
| -a | --all | Show entire history and ignore asset filters. |
| -s | --status | Show system resource bar at the bottom of the terminal. |
| -d | --dashboard | Enable 1-second dashboard mode for real-time metrics. |
| -c | --clear-screen | Clear terminal before starting and on exit. |
| -r | --remote-ip | Use direct connection IP instead of client IP. |
| --help | Show the help menu and usage instructions. |
Activated with the --dashboard or -d flag, this mode transforms clog from a simple log tailer into a full-scale Network Operations Center (NOC) display.
The dashboard provides a high-fidelity, 1-second interval overview of your server's health:
- Real-time Metrics: Tracks live Requests Per Second (RPS) and cumulative request counts to identify traffic spikes as they happen.
- Status Distribution: A visual breakdown of HTTP status codes (Success vs. Client/Server Errors). This allows you to distinguish between a healthy traffic surge and a coordinated DDoS or application failure at a glance.
- System Awareness: When combined with the -s flag, it embeds a resource monitor showing CPU and Memory utilization, allowing you to correlate log spikes with hardware bottlenecks.
- Non-Blocking Engine: Built on a polling architecture that reads from the tail of the log without locking the file, ensuring zero impact on your web server's performance.
Additionally, to add the status bar to the bottom to see uptime, memory use, and CPU use use the --status or -s flag
clog -d -s /var/log/caddy/access.log
Simply point clog at your Caddy access log to see a cleaned-up, human-readable stream and it will print the last 10 lines in the log and continue to tail until stopped (CTRL + C):
clog /path/to/access.log
If you'd like to specify the number of lines to begin with:
clog --lines 20 /path/to/access.log
If you want to limit the tail to a specific host:
clog --host <ip address or host> /path/to/access.log
If you're searching for a specific url, you can define a string to search for:
clog --find <text to find> /path/to/access.log
If you'd like to see only errors:
clog --errors /path/to/access.log
Sometimes you'll want to hide asset-type files to see cleaner results (images, audio, video, JS, css, and more)
clog --hide-assets /path/to/access.log
If you'd like to clear the screen before and after running CLOG:
clog --clear-screen /path/to/access.log
By default, clog prioritizes the Caddy client_ip field to show the visitor's real IP behind proxies, falling back to remote_ip if missing. To force using Caddy's direct connection IP (remote_ip) instead:
clog --remote-ip /path/to/access.logWhen --hide-assets is enabled, clog only displays standard web pages (.html, .php, etc.) and APIs (URLs without extensions). You can dynamically add custom extensions to the whitelist (so they aren't hidden):
clog --hide-assets --assets-whitelist .js,.json,.pdf /path/to/access.logYou can run clog inside a Docker container and expose its terminal UI in a web browser using ttyd. This is ideal for lightweight, remote monitoring without SSH.
Create a docker-compose.yml file:
services:
clog-dashboard:
image: tsl0922/ttyd:alpine
restart: unless-stopped
command: ttyd clog -d -s /var/log/caddy/access.log
ports:
- "7681:7681"
volumes:
- ./clog:/usr/local/bin/clog:ro
- ./access.log:/var/log/caddy/access.log:roRun the container:
docker compose up -dNow open your browser and navigate to http://localhost:7681 to view your live web dashboard.
This project is licensed under the MIT License - see the LICENSE file for more details.
This 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.
Use of this software is at your own risk.