wakewhy

wakewhy is a lightweight CLI tool for Linux that identifies and displays the reasons a system woke from standby/suspend/sleep mode. It queries systemd journal logs and kernel messages to provide a clear summary of recent wakeup events, helping you understand what triggered your system to resume from sleep.

Installation

From Source

Clone the repository and install using pip:

git clone https://github.com/yourusername/wakewhy.git
cd wakewhy
pip install -e .

Alternatively, you can run it directly without installation:

cd wakewhy
python -m wakewhy.cli

Usage

wakewhy [OPTIONS]

Options

• --version: Show version number and exit
• --last N: Show only the last N wakeup events (default: 1 when no other filter is specified)
• --since TIMESTAMP: Show wakeup events since the specified timestamp
  • Supports systemd format: "YYYY-MM-DD HH:MM:SS" (e.g., "2024-01-15 14:30:00")
  • Supports relative format: "1 hour ago", "2 days ago", "yesterday", etc.
• --verbose, -v: Provide detailed information including raw log lines
• --help: Display usage information

Examples

Display the most recent wakeup event:

wakewhy

Show the last 5 wakeup events:

wakewhy --last 5

Display wakeup events from the last hour:

wakewhy --since "1 hour ago"

Display wakeup events since a specific date:

wakewhy --since "2024-01-01 00:00:00"

Show detailed information:

wakewhy --verbose

Combine options:

wakewhy --since "24 hours ago" --last 10 --verbose

How It Works

wakewhy queries Linux system logs to find wakeup events:

1. Primary method: Uses journalctl to query systemd journal for kernel messages related to power management resume/wakeup events
2. Fallback method: If journalctl is not available, falls back to dmesg output
3. Parses log entries for common wakeup patterns (PM resume, ACPI wakeup, systemd-sleep events)
4. Formats and displays the results in a readable format

Known Limitations

• Requires systemd: The tool is designed for systems using systemd (most modern Linux distributions). On systems without systemd, it falls back to dmesg, which may provide less detailed information.
• Permissions: Accessing system logs may require appropriate permissions. On some systems, you may need to run with sudo or be a member of specific groups (e.g., systemd-journal).
• Distribution-specific behavior: Wakeup event logging may vary between Linux distributions and kernel versions. Some wakeup sources may not be logged or may use different log formats.
• Time range: By default, queries the last 24 hours of logs. Use --since to adjust the time range.
• No wakeup events found: If no wakeup events are detected, this could mean:
  • The system hasn't woken from sleep recently
  • The logs have been rotated/cleared
  • The system doesn't log wakeup events in a format wakewhy recognizes
  • Insufficient permissions to access the logs

Exit Codes

• 0: Success (events found and displayed)
• 1: Error occurred (e.g., permission denied, system error)
• 2: No wakeup events found
• 130: Interrupted by user (Ctrl+C)

License

This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues, pull requests, or suggestions for improvement.

See Also

• Linux kernel documentation on power management
• journalctl(1) manual page
• dmesg(1) manual page