added readme
This commit is contained in:
parent
a686e144a8
commit
dec5ac868c
173
Readme.md
Normal file
173
Readme.md
Normal file
@ -0,0 +1,173 @@
|
||||
# cputild - CPU Idle Time Monitor
|
||||
|
||||
## Overview
|
||||
|
||||
**cputild** is a lightweight daemon that continuously monitors CPU utilization by reading from `/proc/stat` and writes the current CPU usage percentage to `/tmp/cputild`. It's designed to run as a background service on Linux systems, providing real-time CPU metrics suitable for other tools to consume.
|
||||
|
||||
## Features
|
||||
|
||||
- **Continuous Monitoring**: Reads CPU statistics every second
|
||||
- **Accurate Calculation**: Uses jiffies-based delta calculation for precise utilization
|
||||
- **Signal Handling**: Gracefully responds to `SIGINT` (Ctrl+C) for clean shutdown
|
||||
- **Daemon Ready**: Includes systemd service configuration for production use
|
||||
- **Efficient I/O**: Reopens files on each iteration for volatile data sources
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Operating System**: Linux (requires `/proc/stat` support)
|
||||
- **Build Tools**: CMake 3.31+, GCC or compatible C11 compiler
|
||||
- **Systemd**: For service management (optional)
|
||||
|
||||
## Building the Project
|
||||
|
||||
### Prerequisites
|
||||
```bash
|
||||
sudo apt install cmake build-essential # Debian/Ubuntu
|
||||
sudo yum install cmake gcc # Fedora/CentOS
|
||||
```
|
||||
|
||||
### Build Process
|
||||
```bash
|
||||
# Using the install script (recommended for production)
|
||||
./install.sh
|
||||
|
||||
# Or manual build
|
||||
mkdir build && cd build
|
||||
cmake -S ../.. -DCMAKE_BUILD_TYPE=RelWithDebInfo
|
||||
cmake --build .
|
||||
# Optional: sudo cmake --install ../.. --prefix /usr/local
|
||||
```
|
||||
|
||||
### Build Options
|
||||
The `CMakeLists.txt` supports multiple build types:
|
||||
- **Debug** (default): For development and debugging
|
||||
- **Release**: Optimized without debug symbols
|
||||
- **RelWithDebInfo** (used by install.sh): Optimized with debug info
|
||||
|
||||
```bash
|
||||
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
|
||||
cmake --build build
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### Automated Installation
|
||||
The provided `install.sh` script handles the complete installation process:
|
||||
```bash
|
||||
./install.sh
|
||||
```
|
||||
|
||||
This script will:
|
||||
1. Create a temporary build directory
|
||||
2. Configure and build the project with `CMake`
|
||||
3. Install the binary to `/usr/local/bin/cputild`
|
||||
4. Copy and enable the systemd service
|
||||
5. Reload systemd daemon
|
||||
|
||||
### Manual Installation
|
||||
```bash
|
||||
sudo cmake --install build --prefix /usr/local
|
||||
sudo cp cputild.service /etc/systemd/system/cputild.service
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable cputild.service
|
||||
sudo systemctl start cputild.service
|
||||
```
|
||||
|
||||
## Systemd Service
|
||||
|
||||
### Service Behavior
|
||||
When running as a systemd service, cputild:
|
||||
- Starts automatically on boot (if enabled)
|
||||
- Restarts on failure (`Restart=on-failure`)
|
||||
- Responds to `SIGINT` for graceful shutdown
|
||||
|
||||
### Management Commands
|
||||
```bash
|
||||
# Enable service (start on boot)
|
||||
sudo systemctl enable cputild.service
|
||||
|
||||
# Start service
|
||||
sudo systemctl start cputild.service
|
||||
|
||||
# Check status
|
||||
sudo systemctl status cputild.service
|
||||
|
||||
# Stop service
|
||||
sudo systemctl stop cputild.service
|
||||
|
||||
# Restart service
|
||||
sudo systemctl restart cputild.service
|
||||
|
||||
# View logs
|
||||
sudo journalctl -u cputild.service
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### Algorithm
|
||||
1. **Read** CPU statistics from `/proc/stat` (in jiffies)
|
||||
2. **Parse** the first line: `cpu user nice system idle iowait irq softirq steal guest guest_nice`
|
||||
3. **Calculate** active time = user + nice + system + irq + softirq + steal + guest + guest_nice
|
||||
4. **Calculate** idle time = iowait + idle
|
||||
5. **Compute** delta (difference) since last measurement
|
||||
6. **Derive** utilization = active_delta / (active_delta + idle_delta) × 100
|
||||
7. **Write** result to `/tmp/cputild` (percentage, 2 decimal places)
|
||||
|
||||
### Output Format
|
||||
```
|
||||
/tmp/cputild: 45.23
|
||||
```
|
||||
The file contains only the number (no newline) for easy parsing by other tools.
|
||||
|
||||
## Signal Handling
|
||||
|
||||
The program uses a simple volatile flag pattern for signal handling:
|
||||
|
||||
| Signal | Effect |
|
||||
|--------|--------|
|
||||
| `SIGINT` (Ctrl+C) | Gracefully sets `running=0` and terminates |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Permission Issues
|
||||
```bash
|
||||
# If you cannot write to /tmp/cputild
|
||||
sudo chmod 666 /tmp
|
||||
```
|
||||
|
||||
### Systemd Service Not Starting
|
||||
```bash
|
||||
# Check for errors
|
||||
sudo systemctl status cputild.service -l
|
||||
|
||||
# Check journal logs
|
||||
sudo journalctl -xeu cputild.service
|
||||
```
|
||||
|
||||
### Manual Test
|
||||
```bash
|
||||
# Test in foreground
|
||||
./build/cputild
|
||||
|
||||
# Verify output
|
||||
cat /tmp/cputild
|
||||
```
|
||||
|
||||
## File Structure
|
||||
```
|
||||
cputild/
|
||||
├── CMakeLists.txt # Build configuration
|
||||
├── install.sh # Installation script
|
||||
├── cputild.service # systemd unit file
|
||||
└── main.c # Source code
|
||||
```
|
||||
|
||||
## Author
|
||||
Linus Vogel <linus@linvogel.ch>
|
||||
|
||||
## License
|
||||
Free to use and modify.
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2026-03-15*
|
||||
Loading…
x
Reference in New Issue
Block a user