Disk Space Watchdog with Tiered Thresholds and Telegram Alert

Summary

This workflow monitors disk usage on a remote Linux server via SSH, applying tiered thresholds (warning and critical) to avoid alert fatigue. It tracks the last known state of each mount point using n8n's workflow static data, so you only receive a notification when a disk changes level (e.g., from OK to warning, or from critical back to OK). Alerts are sent first to a Telegram chat; if that fails, an email is sent as a reliable fallback. The workflow is fully configurable through environment variables, making it easy to adapt without editing the code.

Step-by-Step Nodes

1. Schedule Trigger (No auth) — Runs the workflow every 30 minutes. Configured via interval rule with minutes interval = 30.

2. Check Disk Usage (SSH) (SSH auth – key or password) — Executes the df -P command on the remote server. You must provide credentials (username + SSH key or password) stored in an n8n credential of type "SSH".

3. Parse & Evaluate (No auth) — A Code node that parses the stdout from the SSH command. It reads thresholds from environment variables (DISK_WARN_PCT and DISK_CRIT_PCT, defaulting to 80% and 90%). For each mount point:

   • Compares usage percentage against thresholds.
   • Uses $getWorkflowStaticData('node') to remember the last known level (ok / warning / critical).
   • Only emits an alert when the level changes (including recovery messages when a disk returns below threshold).
   • Outputs { hasAlerts, message, alerts }.

4. Any alerts? (No auth) — An IF node that checks $json.hasAlerts (boolean true). If true, execution goes to the Telegram branch; otherwise the workflow ends silently.

5. Send Telegram Alert (Telegram API – Bot Token auth) — Sends the alert message to a Telegram chat. The chat ID is read from $env.TG_CHAT_ID. The node is set to continueErrorOutput (on error -> next output). On success, no further action. On error, execution flows into the email fallback.

6. Send Email Fallback (SMTP auth – username/password or OAuth2) — Sends the same alert message via email. Uses $env.SMTP_FROM and $env.SMTP_TO for sender and recipient. This ensures alerts are never lost if Telegram is down.

Setup Instructions

1. Prerequisites:

   • A Linux server with SSH access and passwordless sudo (if needed) or a user that can run df -P.
   • A Telegram bot (create one via @BotFather) and obtain its API token.
   • A Telegram chat ID (can be a group or your own ID).
   • An SMTP server (e.g., Gmail, SendGrid, or your own) for email fallback.

2. Environment Variables: Set the following in your n8n environment (e.g., .env or n8n UI > Workflow > Settings):

   • DISK_WARN_PCT (default 80)
   • DISK_CRIT_PCT (default 90)
   • TG_CHAT_ID (e.g., -123456789)
   • SMTP_FROM (e.g., [email protected])
   • SMTP_TO (e.g., [email protected])

3. Create Credentials in n8n:

   • SSH: Add a credential of type "SSH" with the server host, port (22), username, and either password or private key.
   • Telegram: Add a credential of type "Telegram API" with the bot token.
   • SMTP: Add a credential of type "SMTP" with server, port, user, password (and choose authentication method).

4. Bind the credentials to the corresponding nodes in the workflow editor.

Use Cases & Variations

• Server Fleet Monitoring: Duplicate the SSH node or use a loop to check multiple servers; aggregate results in the Code node.
• Different Thresholds per Mount: Extend the Code node to read a JSON mapping from an env variable or static data.
• Escalation Chain: Instead of email fallback, add a PagerDuty or Slack node on error.
• Silence Recoveries: Modify the Code node to skip recovery messages (remove the recovered branch).
• Run less Frequently: Change the Schedule Trigger to hourly or daily.
• Add Grafana/Prometheus integration: Replace the SSH node with an HTTP request to your monitoring API.

This workflow is ideal for sysadmins and DevOps teams who need reliable, noise‑free disk monitoring without a full‑blown observability stack.

{
  "name": "Disk space watchdog with tiered thresholds and Telegram alert",
  "nodes": [
    {
      "parameters": {
        "rule": {
          "interval": [
            {
              "field": "minutes",
              "minutesInterval": 30
            }
          ]
        }
      },
      "id": "f2b10000-0000-4000-8000-000000000001",
      "name": "Schedule Trigger",
      "type": "n8n-nodes-base.scheduleTrigger",
      "typeVersion": 1.2,
      "position": [
        0,
        0
      ]
    },
    {
      "parameters": {
        "resource": "command",
        "command": "df -P"
      },
      "id": "f2b10000-0000-4000-8000-000000000002",
      "name": "Check Disk Usage (SSH)",
      "type": "n8n-nodes-base.ssh",
      "typeVersion": 1,
      "position": [
        220,
        0
      ]
    },
    {
      "parameters": {
        "jsCode": "// Parses the output of \"df -P\", compares it against tiered thresholds (WARN/CRIT)\n// and only reports when a mountpoint CHANGES level. The de-duplication uses n8n's\n// workflow static data, so a disk sitting at 85% for a week alerts once, not 336 times.\n// Thresholds are read from environment variables so the workflow needs no editing.\nconst warnPct = parseInt($env.DISK_WARN_PCT || '80', 10);\nconst critPct = parseInt($env.DISK_CRIT_PCT || '90', 10);\n\nconst raw = $input.first().json.stdout || '';\nconst lines = raw.trim().split('\\n').slice(1);\n\nconst staticData = $getWorkflowStaticData('node');\nif (!staticData.lastLevel) staticData.lastLevel = {};\n\nconst alerts = [];\nfor (const line of lines) {\n  const parts = line.trim().split(/\\s+/);\n  if (parts.length < 6) continue;\n  const filesystem = parts[0];\n  const capacityStr = parts[parts.length - 2];\n  const mount = parts[parts.length - 1];\n  const usedPct = parseInt(capacityStr.replace('%', ''), 10);\n  if (Number.isNaN(usedPct)) continue;\n\n  let level = 'ok';\n  if (usedPct >= critPct) level = 'critical';\n  else if (usedPct >= warnPct) level = 'warning';\n\n  const prevLevel = staticData.lastLevel[mount] || 'ok';\n  if (level !== prevLevel) {\n    staticData.lastLevel[mount] = level;\n    const availGB = (parseInt(parts[parts.length - 3], 10) / 1024 / 1024).toFixed(1);\n    if (level !== 'ok') {\n      alerts.push({ mount, filesystem, usedPct, level, availGB });\n    } else {\n      // Recovery is reported too, so a silent channel means \"nothing changed\",\n      // not \"the workflow died\".\n      alerts.push({ mount, filesystem, usedPct, level, availGB, recovered: true });\n    }\n  }\n}\n\nconst hasAlerts = alerts.length > 0;\nlet message = null;\nif (hasAlerts) {\n  message = alerts.map(a => a.recovered\n    ? `[OK] ${a.mount} back below threshold (${a.usedPct}%)`\n    : `${a.level === 'critical' ? '[CRITICAL]' : '[WARNING]'} ${a.mount} (${a.filesystem}): ${a.usedPct}% used, ${a.availGB} GB free`\n  ).join('\\n');\n}\n\nreturn [{ json: { hasAlerts, message, alerts } }];"
      },
      "id": "f2b10000-0000-4000-8000-000000000003",
      "name": "Parse & Evaluate",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        440,
        0
      ]
    },
// ... truncated (copy to see full JSON)