SERVICE-HEALTH(1)

NAME
service-health - monitor systemd service health status

SYNOPSIS
service-health [OPTIONS] [SERVICE...]

DESCRIPTION
service-health is a command-line tool for monitoring the health of systemd(1) services. With no arguments it prints a colored table of all services showing their status, uptime, memory usage, CPU usage, restart count and boot-enable state. Given one or more SERVICE names, it restricts the output to those services.

The tool is designed to be dependency-light (bash, systemd and coreutils only), to work without an internet connection, and to degrade gracefully when run without root privileges. Some figures (for example exact memory accounting) may only be available to the superuser; missing values are shown as a dash (-).

OPTIONS

(no option)
    Show all services in a table.

SERVICE ...
    Show only the named services. A bare name such as nginx is treated as nginx.service.

--detailed [SERVICE]
    Show a detailed view (description, PID, uptime, memory, CPU, restarts, process tree and, for failed units, the last error). With no argument the detailed view is produced for every service.

--alerts
    Show only services with problems or warnings (failed units, or running units that exceed the configured CPU, memory or restart thresholds).

--failed
    Show only failed services together with their last error message.

--json
    Produce machine-readable JSON. Each object contains the fields name, status, uptime_seconds, memory_mb, cpu_percent, restart_count_24h, enabled_on_boot and last_error. Unavailable numeric values are rendered as null.

--no-colors
    Disable ANSI colors. Colors are also disabled automatically when standard output is not a terminal, when the NO_COLOR environment variable is set, or when USE_COLORS=no is configured.

--watch [--interval N]
    Live monitoring mode: refresh the table every N seconds (default 2). Exit with Ctrl+C.

SERVICE
    --history [--days N] Show the restart and state-change history for SERVICE over the last N days (default 7), derived from the journal.

SERVICE
    --logs [--lines N] [--follow] Show the last N journal entries (default 10) for SERVICE. With --follow the output is tailed continuously, like journalctl -f.

SERVICE
    --dependencies Show what SERVICE requires, wants and is ordered against, plus the units that depend on it. Failed hard dependencies are highlighted.

--config FILE
    Load an alternative configuration file instead of /etc/service-health/config.conf.

--verbose
    Print debugging information (such as the commands executed) to standard error.

--version
    Print the version and exit.

--help
    Print a usage summary and exit.

EXAMPLES

service-health
    Show all services.

service-health nginx postgresql
    Show only nginx and postgresql.

service-health --alerts
    List only services that need attention.

service-health --json --no-colors
    Emit JSON suitable for piping into another tool.

service-health nginx --logs --lines 50
    Show the last 50 journal lines for nginx.

service-health mysql --dependencies
    Show the dependency graph around mysql.

CONFIGURATION
On start-up service-health sources /etc/service-health/config.conf if it exists and is readable. The file is a shell fragment that may set the following variables:

IGNORE_SERVICES
    Comma- or whitespace-separated list of service names to omit from output.

CPU_ALERT_THRESHOLD
    CPU percentage above which a running service is flagged as a warning (default 50).

MEMORY_ALERT_THRESHOLD
    Memory in MB above which a running service is flagged as a warning (default 1000).

RESTART_ALERT_THRESHOLD
    Restart count above which a running service is flagged as a warning (default 5).

USE_COLORS
    Set to no to disable colored output by default.

DEFAULT_FORMAT
    Default output format: table, json or detailed.

WATCH_INTERVAL
    Default refresh interval for --watch in seconds.

EXIT STATUS

0   Success (this includes the case of no services found).

1   A requested service was not found, or systemd is unavailable.

2   Invalid command-line usage.

NOTES
The CPU percentage is the average over the lifetime of the process, as reported by ps(1), not an instantaneous sample. The restart count shown in the table is the NRestarts counter maintained by systemd since the unit was loaded; use --history for a journal-based view of restarts within a time window.

FILES

/etc/service-health/config.conf
    Optional system-wide configuration file.

SEE ALSO
systemctl(1), journalctl(1), systemd(1), ps(1)

AUTHOR
Phillip Fürpaß <pfurpass@gmail.com>

COPYRIGHT
Copyright © 2026 Phillip Fürpaß. License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.