Skip to content

Latest commit

 

History

History
118 lines (89 loc) · 3.48 KB

QUICKSTART.md

File metadata and controls

118 lines (89 loc) · 3.48 KB

Overseer - Quick Reference

Installation (30 seconds)

  1. Download Overseer.zip
  2. Unzip by double-clicking
  3. Drag Overseer.app to your Applications folder
  4. Open the app:
    • First time: Right-click → "Open" → Click "Open" in the dialog
    • Or run in Terminal: xattr -cr /Applications/Overseer.app && open /Applications/Overseer.app
  5. Look for the eye icon (👁️) in your menu bar

Usage

Menu Bar Icon

  • Click: Opens settings panel
  • Right-Click: Quick actions menu

Settings Panel (Click Icon)

  • CPU Threshold: When to log (default: 80%)
  • Memory Threshold: When to log (default: 85%)
  • Sampling Interval: How often to check (default: 5s)
  • Log Rate: How often to log same process (default: 5s)

Quick Menu (Right-Click Icon)

  • Monitoring status (Active/Paused)
  • Pause/Resume monitoring
  • Current thresholds
  • Open logs folder
  • Quit app

What Gets Logged?

When a process exceeds thresholds, you'll see:

[2026-03-17 14:05:23] [CPU] Chrome (1234): CPU=95.3%, MEM=2.1GB (duration: 15s)

Log Location: ~/Library/Logs/Overseer/overseer-YYYY-MM-DD.log

Common Use Cases

Monitor Build Processes

Set CPU threshold to 70% to catch long-running builds:

  1. Click icon → Adjust CPU slider to 70%
  2. Run your build
  3. Check logs to see CPU usage over time

Track Memory Leaks

Set memory threshold to 75%:

  1. Click icon → Adjust Memory slider to 75%
  2. Run your app
  3. Watch for sustained high memory usage in logs

System Performance Issues

Lower CPU threshold to 50% to see all active processes:

  1. Right-click icon → Shows active processes
  2. Click icon → View "Top Processes" section
  3. Check logs for patterns

Troubleshooting

Problem Solution
Icon not appearing Check Activity Monitor for "Overseer", restart app
"App is damaged" error Run: xattr -cr /Applications/Overseer.app
High CPU from Overseer itself Increase sampling interval to 10-30s
No logs created Check ~/Library/Logs/Overseer/ exists
Wrong thresholds Click icon, adjust sliders, changes save automatically

System Requirements

  • macOS: 13.0 (Ventura) or later
  • RAM: ~50MB
  • CPU: <2% during normal operation
  • Disk: ~1MB for app + logs (auto-rotates after 30 days)

Technical Details

  • Language: Swift 5.9
  • APIs: Uses proc_pidinfo() and task_info() for efficient monitoring
  • Monitoring: Top 20 processes by CPU, every 5 seconds (configurable)
  • Logging: Asynchronous writes, daily rotation, 30-day retention
  • Accuracy: Per-core CPU percentages (100% = full core usage)

Tips

✅ Do:

  • Leave running 24/7 (very low resource usage)
  • Adjust thresholds based on your workflow
  • Check logs weekly to spot patterns
  • Share logs when reporting performance issues

❌ Don't:

  • Set sampling interval < 3s (higher overhead)
  • Set thresholds too low (creates noise in logs)
  • Run multiple instances (one per user is enough)

Getting Help

View logs: Right-click icon → "Open Logs Folder"

Report issues with:

  • macOS version: sw_vers
  • Last 20 log lines: tail -20 ~/Library/Logs/Overseer/overseer-*.log
  • What you were doing when issue occurred

Uninstall

  1. Right-click icon → Quit
  2. Delete: /Applications/Overseer.app
  3. Delete logs: ~/Library/Logs/Overseer/ (optional)
  4. Delete settings: defaults delete com.overseer.app (optional)

Version: 1.0.0
Support: Check logs first, then contact IT with log snippets