Uptime

Sysops toolkit for tracking and managing uptime-related operations. Log scans, monitor events, track alerts, run benchmarks, and manage backups — all with timestamped history and multi-format export.

Commands

All data commands accept optional input. Without input, they display the 20 most recent entries. With input, they log a new timestamped entry.

Core Operations

| Command | Description | |---------|-------------| | uptime scan [input] | Log or view scan entries — track scanning operations | | uptime monitor [input] | Log or view monitoring events — track ongoing observations | | uptime report [input] | Log or view report entries — record generated reports | | uptime alert [input] | Log or view alert entries — track warnings and incidents | | uptime top [input] | Log or view top-priority entries — highlight key items | | uptime usage [input] | Log or view usage entries — track resource utilization | | uptime check [input] | Log or view check entries — record verification tasks | | uptime fix [input] | Log or view fix entries — document applied fixes | | uptime cleanup [input] | Log or view cleanup entries — track maintenance work | | uptime backup [input] | Log or view backup entries — record backup operations | | uptime restore [input] | Log or view restore entries — track restore operations | | uptime log [input] | Log or view general log entries | | uptime benchmark [input] | Log or view benchmark entries — record performance tests | | uptime compare [input] | Log or view comparison entries — track A/B comparisons |

Utility Commands

| Command | Description | |---------|-------------| | uptime stats | Show summary statistics: entry counts per category, total entries, data size, and earliest record date | | uptime export <fmt> | Export all data in json, csv, or txt format to the data directory | | uptime search <term> | Search across all log files for a term (case-insensitive) | | uptime recent | Show the 20 most recent entries from the activity history log | | uptime status | Health check: version, data directory, total entries, disk usage, last activity | | uptime help | Show full command listing | | uptime version | Print version string (uptime v2.0.0) |

Data Storage

All data is stored locally in ~/.local/share/uptime/:

Per-command logs: scan.log, monitor.log, alert.log, backup.log, etc. — one file per command type
History log: history.log — unified activity log with timestamps
Export files: export.json, export.csv, export.txt — generated on demand
Format: Each entry is stored as YYYY-MM-DD HH:MM|<input> (pipe-delimited)

Set the UPTIME_DIR environment variable to change the data directory.

Requirements

bash (with set -euo pipefail strict mode)
Standard Unix tools: date, wc, du, head, tail, grep, basename, cat
No external dependencies or API keys required

When to Use

Tracking uptime scan results — Log periodic scan outputs and review scan history over time
Monitoring infrastructure events — Record monitoring observations, alerts, and incidents with timestamps for audit trails
Documenting fixes and maintenance — Use fix, cleanup, and restore to keep a structured record of all maintenance activities
Benchmarking and comparing performance — Log benchmark results and comparisons across different runs or configurations
Exporting operational data — Pull all logged data into JSON, CSV, or TXT for external analysis, dashboards, or compliance reports

Examples

# Log a scan result
uptime scan "web-server-01 responded 200 in 45ms"

# Record an alert
uptime alert "disk usage at 92% on db-server-02"

# Log a backup operation
uptime backup "full backup of production DB completed 3.2GB"

# View recent monitoring entries
uptime monitor

# Search for entries mentioning a specific server
uptime search "web-server-01"

# Get summary statistics across all categories
uptime stats

# Export everything to JSON for analysis
uptime export json

# Check tool health and data directory status
uptime status

# View the 20 most recent activity entries
uptime recent

How It Works

Uptime uses a simple append-only log architecture. Each command type writes to its own .log file, and all activity is also appended to a central history.log for chronological tracking. The stats command aggregates counts across all log files. The export command reads all logs and serializes them into the requested format. The search command performs case-insensitive grep across all log files.