Sign inSign up

nextstage/cpu-usage-agent

By nextstage

Updated 6 months ago

This is a PHP code that implements a CPU usage monitor on a server.

Image
Monitoring & observability
0

1.2K

nextstage/cpu-usage-agent repository overview

CPU And Disk Usage Monitor Agent

Overview

This project is a CPU and disk usage monitoring agent that runs inside a Docker container.
It sends notifications to a webhook URL whenever CPU usage or disk space crosses configurable limits.

Prerequisites
  • Docker installed and running.
  • The host must have HTTP access to the notification URL.
  • A user with permission to run docker (use sudo if needed).
Quick install script

Use the script below to stop any existing container, clean unused Docker resources, pull the latest image, and start the container with all required environment variables.

  1. Save the content below to a file, for example install-cpu-agent.sh.
  2. Edit only the variables in the “Configure only this variables” section.
  3. Make it executable: chmod +x install-cpu-agent.sh.
  4. Run: ./install-cpu-agent.sh (with super user or sudo).
#!/bin/bash

# Configure only this variables.
REFERENCE="YOUR-APP-NAME-OR-REFERENCE"
URL_NOTIFY="http://YOUR-BACKEND-URL-TO-WEBHOOKS?_ref=${REFERENCE}"
SECONDS_TO_INIT=60
LOWER_USAGE_LIMIT=0
HIGHEST_USAGE_LIMIT=70
MINUTES_INTERVAL_NOTIFY=60
MINUTES_ON_ALARME=3
DISK_CRITICAL_AVAILABLE=25
CONTAINER_NAME="cpu-usage-agent"


# Dont be need to change the script, just the variables.
get_external_ip_metadata() {
    # helper para validar IPv4 simples
    is_ipv4() {
        echo "$1" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$'
    }

    # Tenta AWS
    aws_ip=$(curl -s --max-time 0.2 http://169.254.169.254/latest/meta-data/public-ipv4 2>/dev/null)
    if [ -n "$aws_ip" ] && is_ipv4 "$aws_ip"; then
        echo "$aws_ip (AWS)"
        return 0
    fi

    # Tenta GCP
    gcp_ip=$(curl -s --max-time 0.2 -H "Metadata-Flavor: Google" \
        "http://169.254.169.254/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip" 2>/dev/null)
    if [ -n "$gcp_ip" ] && is_ipv4 "$gcp_ip"; then
        echo "$gcp_ip (GCP)"
        return 0
    fi

    # Tenta Azure
    azure_ip=$(curl -s --max-time 0.2 -H "Metadata:true" \
        "http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2021-02-01&format=text" 2>/dev/null)
    if [ -n "$azure_ip" ] && is_ipv4 "$azure_ip"; then
        echo "$azure_ip (Azure)"
        return 0
    fi

    # Fallback: tenta achar IP não privado nas interfaces locais (sem sair para fora)
    local_ip=$(ip -4 addr show | awk '/inet / {print $2}' | cut -d/ -f1 \
        | grep -Ev '^(10\.|172\.(1[6-9]|2[0-9]|3[0-1])\.|192\.168\.)' | head -n1)
    if [ -n "$local_ip" ] && is_ipv4 "$local_ip"; then
        echo "$local_ip (Local)"
        return 0
    fi

    echo ""
}

# Others envs
internal_ip=$(hostname -I | awk '{print $1}')
external_ip=$(get_external_ip_metadata)
HOSTNAME=$(hostname)
IP_EXTERNAL="Internal: ${internal_ip} | External: ${external_ip}"

echo ""
echo "#### NSUtil - Usage Agent ####"
echo "CONTAINER NAME: ${CONTAINER_NAME}"
echo "REFERENCE: ${REFERENCE}"
echo "HOSTNAME: $(hostname)"
echo "IP_EXTERNAL: ${IP_EXTERNAL}"

docker stop ${CONTAINER_NAME} > /dev/null 2>&1
docker system prune -f > /dev/null 2>&1
docker pull nextstage/cpu-usage-agent > /dev/null 2>&1
docker run \
    --restart always \
    -e URL_NOTIFY="${URL_NOTIFY}" \
    -e SECONDS_TO_INIT="${SECONDS_TO_INIT}" \
    -e LOWER_USAGE_LIMIT="${LOWER_USAGE_LIMIT}" \
    -e HIGHEST_USAGE_LIMIT="${HIGHEST_USAGE_LIMIT}" \
    -e MINUTES_INTERVAL_NOTIFY="${MINUTES_INTERVAL_NOTIFY}" \
    -e MINUTES_ON_ALARME="${MINUTES_ON_ALARME}" \
    -e DISK_CRITICAL_AVAILABLE="${DISK_CRITICAL_AVAILABLE}" \
    -e HOST_HOSTNAME="${HOSTNAME}" \
    -e IP_EXTERNAL="${IP_EXTERNAL}" \
    -d \
    --name ${CONTAINER_NAME} \
    nextstage/cpu-usage-agent > /dev/null 2>&1

echo "Finished! Container started successfully!"
echo "Container status:"
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.RunningFor}}" | sed "s/$CONTAINER_NAME/\x1b[32m&\x1b[0m/g"
echo ""
Important variables
  • REFERENCE: identifies your application/environment. It is used in the _ref parameter of the notification URL.
  • URL_NOTIFY: full webhook URL that will receive the alerts.
    • In the example, it already contains an apikey and _ref=${REFERENCE}.
  • SECONDS_TO_INIT: number of seconds the agent waits before starting to monitor.
  • LOWER_USAGE_LIMIT / HIGHEST_USAGE_LIMIT: CPU usage range considered acceptable. Alerts are sent when usage is outside this range.
  • MINUTES_INTERVAL_NOTIFY: minimum interval (in minutes) between notifications.
  • MINUTES_ON_ALARME: time (in minutes) that the agent stays in alarm state.
  • DISK_CRITICAL_AVAILABLE: minimum free disk space percentage before triggering an alert.
  • CONTAINER_NAME: Docker container name that will be created/updated.
What the script does
  • Stops an existing container with the configured name (if it exists).
  • Runs docker system prune -f to clean unused resources.
  • Pulls the latest nextstage/cpu-usage-agent image.
  • Starts the container with --restart always and all required environment variables.
  • Shows the container status at the end, highlighting the configured name.

Tag summary

Content type

Image

Digest

sha256:cc1d6841e

Size

48.1 MB

Last updated

6 months ago

docker pull nextstage/cpu-usage-agent