Argus

Argus is a lightweight service monitoring daemon for Unix systems. It continuously monitors system services, Docker containers, Kubernetes clusters, and system resources, exposes a REST API for state inspection and Prometheus metrics, and sends email alerts when failures, overloads, or recoveries occur. Optionally, it can attach logs to notification emails to speed up diagnosis.

Meaning of the Name

The name Argus comes from Greek mythology. Argus was a giant with many eyes who never slept, symbolizing constant vigilance. Likewise, this tool keeps a constant watch over your system, ensuring nothing goes unnoticed.

Why I Created This Service

I created Argus to simplify server monitoring on Unix systems.

I wanted:

• A simple and reliable daemon
• No heavy dependencies or external services
• Immediate email alerts on failures or resource exhaustion
• A persistent state to avoid alert spam
• A small API to inspect system health programmatically
• Prometheus metrics export for integration with monitoring stacks

Argus is designed to run quietly in the background and only speak when something actually matters.

Features

• Monitor systemd services (Linux)
• Monitor rc services (for BSD systems)
• Monitor Docker containers
• Monitor Kubernetes clusters
• Monitor CPU usage
• Monitor memory usage
• Monitor disk usage
• Monitor system temperature
• Feature flags to enable/disable monitors at runtime
• Email alerts on failures or threshold violations
• Optional recovery notifications
• Attach journalctl logs to alert emails
• Attach Docker container logs to alert emails
• Configurable polling interval
• Persistent state to prevent duplicate alerts
• Built-in HTTP REST API for status inspection
• Prometheus metrics endpoint for integration with monitoring tools

Requirements

• Linux system with systemd or Unix system with rc
• Rust 1.70+ (or latest stable)
• Docker (optional, for container monitoring)
• Kubernetes cluster access (optional)
• SMTP account for email notifications
• journalctl available (for systemd logs)
• Hardware temperature sensors (optional, for temperature monitoring)

Installation

1. Clone the repository:

git clone https://codeberg.org/alimiracle/argus
cd argus

2. Build the project:

cargo build --release

3. Install the binary:

sudo cp target/release/argus /usr/local/bin/
sudo chmod +x /usr/local/bin/argus

Configuration

Create a config.toml file (see config.example.toml).

General settings

• general.check_interval_seconds Polling interval in seconds

• general.state_file Path to the persistent state file

• general.send_recovery_emails Enable recovery notifications

Feature flags (global)

• general.enable_systemd Enable monitoring of systemd services

• general.enable_rc Enable monitoring of BSD rc.d services

• general.enable_docker Enable monitoring of Docker containers

• general.enable_k8s Enable monitoring of Kubernetes clusters

• general.enable_cpu Enable CPU usage monitoring

• general.enable_memory Enable memory usage monitoring

• general.enable_disk Enable disk usage monitoring

• general.enable_temperature Enable temperature monitoring

These control which monitors are active.

Resource thresholds

• general.cpu_threshold_percent CPU usage percentage that triggers an alert (e.g., 90.0)

• general.memory_threshold_percent Memory usage percentage that triggers an alert (e.g., 90.0)

• general.disk_threshold_percent Disk usage percentage that triggers an alert (e.g., 90.0)

• general.temperature_threshold_celsius Temperature threshold in ーC that triggers an alert (e.g., 80.0)

Email configuration

• email.smtp_server SMTP server hostname or IP address

• email.smtp_port SMTP server port (465 for SMTPS, 587 for STARTTLS)

• email.username SMTP authentication username

• email.password SMTP authentication password

• email.from Sender email address

• email.to Recipient email address for alerts

• email.use_tls Enable TLS encryption (true/false)

• email.allow_invalid_certs Allow invalid or self-signed certificates (true/false)

API configuration

• api.enable Enable the REST API server (true/false)

• api.listen IP address to listen on (e.g., "127.0.0.1" for localhost, "0.0.0.0" for all interfaces)

• api.port Port for the REST API server (default: 8080)

Logs

• logs.attach_journal Attach journalctl output to alerts

• logs.journal_lines Number of systemd journal log lines to attach

• logs.attach_docker Attach Docker container logs to alerts

• logs.docker_lines Number of Docker log lines to attach

• logs.attach_on_recovery Attach logs to recovery emails

Example Usage

Run Argus with the default configuration:

./argus

Or specify a custom config path:

./argus /etc/argus/config.toml

API Server

Argus exposes an HTTP API for inspecting the current monitoring state and exporting Prometheus metrics.

Configuration

Configure the API server in your config.toml:

[api]
enable = true
listen = "127.0.0.1" # or "0.0.0.0" for all interfaces
port = 8080

Endpoints

GET /state

Returns the current monitoring state as JSON.

Example:

curl http://127.0.0.1:8080/state

Response:

{
 "cpu_usage_percent": 45.2,
 "memory_used_mb": 8192,
 "memory_total_mb": 16384,
 "disk_used_mb": 102400,
 "disk_total_mb": 512000,
 "temperature_celsius": 55.0,
 "services": {
 "nginx": true,
 "postgresql": true,
 "redis": false
 },
 "containers": {
 "web_app": true,
 "database": true
 },
 "k8s_pods": {
 "my-pod-123": "Running",
 "another-pod-456": "Pending"
 }
}

GET /metrics

Returns Prometheus-formatted metrics for integration with monitoring tools like Prometheus and Grafana.

Example:

curl http://127.0.0.1:8080/metrics

Response:

# HELP cpu_usage_percent Current CPU usage percent
# TYPE cpu_usage_percent gauge
cpu_usage_percent 45.2
# HELP memory_used_mb Used memory in MB
# TYPE memory_used_mb gauge
memory_used_mb 8192
# HELP memory_total_mb Total memory in MB
# TYPE memory_total_mb gauge
memory_total_mb 16384
# HELP disk_used_mb Used disk space in MB
# TYPE disk_used_mb gauge
disk_used_mb 102400
# HELP disk_total_mb Total disk space in MB
# TYPE disk_total_mb gauge
disk_total_mb 512000
# HELP temperature_celsius Current temperature in Celsius
# TYPE temperature_celsius gauge
temperature_celsius 55
# HELP service_nginx Service nginx running
# TYPE service_nginx gauge
service_nginx 1
# HELP container_web_app Container web_app running
# TYPE container_web_app gauge
container_web_app 1
# HELP k8s_pod_status Kubernetes pod status (1 = Running, 0 = Not Running)
# TYPE k8s_pod_status gauge
k8s_pod_status{pod="my-pod-123"} 1
k8s_pod_status{pod="another-pod-456"} 0

Integration with Prometheus

Add this to your prometheus.yml:

scrape_configs:- job_name:'argus'static_configs:- targets:['127.0.0.1:8080']metrics_path:'/metrics'scrape_interval:30s

Logs and State

• Argus stores a state file to track the last known status of monitored targets.
• This prevents duplicate alerts when a service, container, or resource remains in a failed or overloaded state.
• The state file location is configured in config.toml under general.state_file.
• By default, the state file is stored at /var/lib/argus/state.json.

Systemd Service

To run Argus as a systemd service, create /etc/systemd/system/argus.service:

[Unit]
Description=Argus Service Monitor
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/argus /etc/argus/config.toml
Restart=always
RestartSec=10
User=root
[Install]
WantedBy=multi-user.target

Then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable argus
sudo systemctl start argus
sudo systemctl status argus

Troubleshooting

Check Argus logs

sudo journalctl -u argus -f

Test email configuration

Make sure your SMTP settings are correct and the SMTP server is reachable.

Verify API is running

curl http://127.0.0.1:8080/state

Check permissions

Ensure Argus has permission to read systemd services, Docker containers, and system resources.

License

This project is licensed under the GNU General Public License v3 (GPLv3).