docs: documentar exibição do body nas notificações do Telegram

Co-authored-by: Claude <noreply@anthropic.com>

README.md

@@ -4,42 +4,80 @@ Simple health check script for Healthchecks.io, designed to run every minute usi
 
 ## Installation
 
-1. Copy the systemd unit files to your user systemd directory:
+### 1. Install Git
 
 ```bash
-   mkdir -p ~/.config/systemd/user
-   cp systemd/chamado-health.service ~/.config/systemd/user/
-   cp systemd/chamado-health.timer ~/.config/systemd/user/
+# Debian/Ubuntu
+sudo apt update && sudo apt install -y git python3
+
+# RHEL/CentOS/Fedora
+sudo dnf install -y git python3
 ```
 
-2. Update the `HEALTHCHECK_URL` in the service unit or set it in `~/.config/chamado-health`.
-
-3. Reload the user daemon and enable the timer:
+### 2. Configure Git identity
 
 ```bash
-   systemctl --user daemon-reload
-   systemctl --user enable --now chamado-health.timer
-   systemctl --user status chamado-health.timer
+git config --global user.name "Your Name"
+git config --global user.email "you@example.com"
 ```
 
-4. If you change the service or timer unit later, reload the user daemon and restart the timer using the unit name (not the file path):
+### 3. Clone the repository
 
 ```bash
-   systemctl --user daemon-reload
-   systemctl --user restart --now chamado-health.timer
-   systemctl --user list-timers --all | grep chamado-health
-   journalctl --user -u chamado-health.service -n 10 --no-pager
+mkdir -p ~/src
+git clone https://github.com/SantosFC/health-check.git ~/src/health-check
+cd ~/src/health-check
 ```
 
+### 4. Run the setup script
+
+```bash
+bash setup.sh
+```
+
+The script will:
+1. Ask for your `HEALTHCHECK_URL` (Healthchecks.io ping endpoint) and validate it.
+2. Ask for a `DEVICE_NAME` to identify this machine.
+3. Save the configuration to `~/.config/health-check`.
+4. Install and enable the systemd timer.
+5. Run a test ping to confirm everything works.
+
+> Both `HEALTHCHECK_URL` and `DEVICE_NAME` can be pre-set as environment variables to skip the interactive prompts:
+> ```bash
+> HEALTHCHECK_URL=https://hc-ping.com/<your-uuid> DEVICE_NAME=my-machine bash setup.sh
+> ```
+
 ## Configuration
 
-- `HEALTHCHECK_URL` must be set to your Healthchecks.io ping endpoint.
-- You can also pass the URL as a command-line argument to the script:
+The configuration file is `~/.config/health-check`:
+
+```
+HEALTHCHECK_URL=https://hc-ping.com/<your-uuid>
+DEVICE_NAME=my-machine
+```
+
+You can also pass the URL as a command-line argument to the script:
 
 ```bash
 ./healthcheck.py https://hc-ping.com/<your-uuid>
 ```
 
+## Systemd units
+
+The unit files installed to `~/.config/systemd/user/` are:
+
+- `health-check.service`
+- `health-check.timer`
+
+To reload and restart after changes:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user restart health-check.timer
+systemctl --user list-timers --all | grep health-check
+journalctl --user -u health-check.service -n 10 --no-pager
+```
+
 ## Script behavior
 
 - Sends an HTTP GET to the configured Healthchecks.io URL.

docs/ping-payload.md

@@ -0,0 +1,133 @@
+# Ping Payload Standard
+
+This document defines the standard payload for all health check pings sent to Healthchecks.io across all agents (scripts, bots, services).
+
+## Why not use an existing library?
+
+The [`healthchecks-io`](https://pypi.org/project/healthchecks-io/) package on PyPI focuses on the management API and does not send a custom body payload. This library fills that gap with an opinionated, consistent payload that identifies the agent, device, IPs, and uptime on every ping.
+
+---
+
+## Using as a Python module
+
+Install directly from the repository:
+
+```bash
+pip install git+https://github.com/SantosFC/health-check.git
+```
+
+### Basic usage
+
+```python
+from health_check import ping, ping_fail
+
+url = "https://hc-ping.com/<your-uuid>"
+
+try:
+    status = ping(url, agent="my-telegram-bot", device="my-server")
+    if 200 <= status < 300:
+        print("Ping OK")
+    else:
+        ping_fail(url, agent="my-telegram-bot", device="my-server")
+except Exception as exc:
+    ping_fail(url, agent="my-telegram-bot", device="my-server")
+    raise
+```
+
+### Loading config from file
+
+```python
+from health_check import load_config, ping
+
+config = load_config()  # reads ~/.config/health-check
+ping(config["HEALTHCHECK_URL"], agent="my-bot", device=config["DEVICE_NAME"])
+```
+
+### Custom config path
+
+```python
+from pathlib import Path
+from health_check import load_config
+
+config = load_config(config_file=Path("/etc/my-bot/config"))
+```
+
+### Timeout
+
+```python
+ping(url, agent="my-bot", device="server", timeout=5)
+```
+
+---
+
+## HTTP Request
+
+- **Method:** `POST`
+- **URL:** `https://hc-ping.com/<uuid>`
+
+## Headers
+
+| Header | Value |
+|---|---|
+| `User-Agent` | `health-check/<version>` |
+| `Content-Type` | `application/json` |
+
+## Body
+
+```json
+{
+  "user": "<agent-name>",
+  "device": "<device-name>",
+  "ips": ["<ip1>", "<ip2>"],
+  "uptime": "<Xd Yh Zm>"
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `user` | `string` | Name of the agent sending the ping (script, bot, service) |
+| `device` | `string` | Name of the device or host where the agent runs |
+| `ips` | `array of strings` | List of IP addresses of the device |
+| `uptime` | `string` | Device uptime formatted as `Xd Yh Zm` |
+
+## Example
+
+```json
+{
+  "user": "my-telegram-bot",
+  "device": "my-server",
+  "ips": ["192.168.1.10", "10.0.0.5"],
+  "uptime": "3d 14h 22m"
+}
+```
+
+## Failure Ping
+
+On error, agents must send a POST to `<uuid>/fail` with the same body. The `ping_fail` function handles this automatically.
+
+---
+
+## Telegram Notifications
+
+Healthchecks.io includes the ping body as **Last Ping Body** in Telegram notifications (UP, DOWN, and failure events). The body is displayed as raw JSON with syntax highlighting.
+
+Example of what appears in the Telegram message:
+
+```
+🟢 The check mySoccer is now UP.
+
+Project: FastAPI
+Tags: Telegram, Soccer
+Period: 2 minutes
+Total Pings: 860
+Last Ping: Success, a second ago
+Last Ping Body:
+{"user":"ronaldo","device":"sandbox","ips":["192.168.122.71","fe80::f9f:d854:2bed:e454","100.70.8.112"],"uptime":"0d 2h 47m"}
+```
+
+### Implications for payload design
+
+- Keep field names short and meaningful — they appear directly in the notification
+- `user` identifies who sent the ping (agent name)
+- `device` and `uptime` give immediate context for diagnosing incidents without leaving Telegram
+- Avoid sensitive data in the body (IPs are acceptable; avoid tokens or passwords)

health_check/__init__.py

@@ -0,0 +1,7 @@
+"""health-check: lightweight Healthchecks.io ping client."""
+
+from health_check._config import load_config
+from health_check._ping import ping, ping_fail
+
+__version__ = "1.0.2"
+__all__ = ["ping", "ping_fail", "load_config"]

health_check/_config.py

@@ -0,0 +1,17 @@
+import os
+from pathlib import Path
+
+
+def load_config(config_file: Path | None = None) -> dict:
+    """Load configuration from file, falling back to environment variables."""
+    path = config_file or Path.home() / ".config" / "health-check"
+    config = {}
+    if path.exists():
+        for line in path.read_text().splitlines():
+            if "=" in line:
+                key, value = line.split("=", 1)
+                config[key.strip()] = value.strip()
+
+    config.setdefault("HEALTHCHECK_URL", os.environ.get("HEALTHCHECK_URL", ""))
+    config.setdefault("DEVICE_NAME", os.environ.get("DEVICE_NAME", "unknown"))
+    return config

health_check/_ping.py

@@ -0,0 +1,50 @@
+import json
+import subprocess
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+_USER_AGENT = "health-check/1.0.2"
+
+
+def _build_body(agent: str, device: str) -> bytes:
+    try:
+        ips = subprocess.check_output(["hostname", "-I"], timeout=5).decode().split()
+    except Exception:
+        ips = []
+
+    try:
+        seconds = int(float(Path("/proc/uptime").read_text().split()[0]))
+        d, rem = divmod(seconds, 86400)
+        h, rem = divmod(rem, 3600)
+        m = rem // 60
+        uptime = f"{d}d {h}h {m}m"
+    except Exception:
+        uptime = "unknown"
+
+    return json.dumps({"user": agent, "device": device, "ips": ips, "uptime": uptime}).encode()
+
+
+def ping(url: str, agent: str, device: str, timeout: int = 10) -> int:
+    """Send a success ping to Healthchecks.io. Returns the HTTP status code."""
+    body = _build_body(agent, device)
+    req = urllib.request.Request(
+        url, data=body, method="POST",
+        headers={"User-Agent": _USER_AGENT, "Content-Type": "application/json"},
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as response:
+        return response.getcode()
+
+
+def ping_fail(url: str, agent: str, device: str, timeout: int = 10) -> None:
+    """Send a failure ping to Healthchecks.io (<uuid>/fail)."""
+    body = _build_body(agent, device)
+    fail_url = url.rstrip("/") + "/fail"
+    try:
+        req = urllib.request.Request(
+            fail_url, data=body, method="POST",
+            headers={"User-Agent": _USER_AGENT, "Content-Type": "application/json"},
+        )
+        urllib.request.urlopen(req, timeout=timeout)
+    except Exception:
+        pass

healthcheck.py

@@ -1,71 +1,47 @@
 #!/usr/bin/env python3
-import json
+"""CLI entry point for health-check."""
+
 import os
 import sys
-import urllib.error
-import urllib.request
 from datetime import datetime, timezone
-from pathlib import Path
 
-PAYLOAD = json.dumps({"name": "Ronaldo Freitas Dias"}).encode()
+import urllib.error
+from health_check import ping, ping_fail, load_config
+
+AGENT = "Ronaldo Freitas Dias"
 
 
-def load_url_from_config():
-    config_file = Path.home() / ".config" / "health-monitor"
-    if config_file.exists():
-        for line in config_file.read_text().splitlines():
-            if line.startswith("HEALTHCHECK_URL="):
-                return line.split("=", 1)[1].strip()
-    return None
-
-
-HEADERS = {"User-Agent": "health-monitor/1.0", "Content-Type": "application/json"}
-
-
-def ping(url: str, timeout: int) -> int:
-    req = urllib.request.Request(url, data=PAYLOAD, method="GET", headers=HEADERS)
-    with urllib.request.urlopen(req, timeout=timeout) as response:
-        return response.getcode()
-
-
-def ping_fail(url: str, timeout: int) -> None:
-    fail_url = url.rstrip("/") + "/fail"
-    try:
-        req = urllib.request.Request(fail_url, data=PAYLOAD, method="GET", headers=HEADERS)
-        urllib.request.urlopen(req, timeout=timeout)
-    except Exception:
-        pass
-
-
-def main():
-    url = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("HEALTHCHECK_URL") or load_url_from_config()
+def main() -> int:
+    config = load_config()
+    url = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("HEALTHCHECK_URL") or config.get("HEALTHCHECK_URL")
     if not url:
         print("ERROR: HEALTHCHECK_URL not set", file=sys.stderr)
         return 1
 
+    device = os.environ.get("DEVICE_NAME") or config.get("DEVICE_NAME", "unknown")
     timeout = int(os.environ.get("HEALTHCHECK_TIMEOUT", 10))
 
     try:
-        status = ping(url, timeout)
+        status = ping(url, agent=AGENT, device=device, timeout=timeout)
         if 200 <= status < 300:
-            print(f"{datetime.now(timezone.utc).isoformat()} status={status} url={url}")
+            print(f"{datetime.now(timezone.utc).isoformat()} status={status} device={device} url={url}")
             return 0
 
         print(f"ERROR: HTTP {status} url={url}", file=sys.stderr)
-        ping_fail(url, timeout)
+        ping_fail(url, agent=AGENT, device=device, timeout=timeout)
         return 2
 
     except urllib.error.HTTPError as exc:
         print(f"HTTPError {exc.code} {exc.reason} url={url}", file=sys.stderr)
-        ping_fail(url, timeout)
+        ping_fail(url, agent=AGENT, device=device, timeout=timeout)
         return 3
     except urllib.error.URLError as exc:
         print(f"URLError {exc.reason} url={url}", file=sys.stderr)
-        ping_fail(url, timeout)
+        ping_fail(url, agent=AGENT, device=device, timeout=timeout)
         return 4
     except Exception as exc:
         print(f"ERROR {exc} url={url}", file=sys.stderr)
-        ping_fail(url, timeout)
+        ping_fail(url, agent=AGENT, device=device, timeout=timeout)
         return 5
 
 

install_systemd.fish

@@ -1,17 +1,17 @@
 #!/usr/bin/env fish
 
 set SCRIPT_DIR (dirname (realpath (status filename)))
-set CONFIG_FILE "$HOME/.config/health-monitor"
+set CONFIG_FILE "$HOME/.config/health-check"
 
 mkdir -p "$HOME/.config/systemd/user"
-cp "$SCRIPT_DIR/systemd/health-monitor.service" "$HOME/.config/systemd/user/"
-cp "$SCRIPT_DIR/systemd/health-monitor.timer" "$HOME/.config/systemd/user/"
+cp "$SCRIPT_DIR/systemd/health-check.service" "$HOME/.config/systemd/user/"
+cp "$SCRIPT_DIR/systemd/health-check.timer" "$HOME/.config/systemd/user/"
 
 echo "Arquivos de unit systemd copiados para ~/.config/systemd/user/."
 
 systemctl --user daemon-reload
-systemctl --user enable --now health-monitor.timer
-systemctl --user status --no-pager health-monitor.timer
+systemctl --user enable --now health-check.timer
+systemctl --user status --no-pager health-check.timer
 
 # Ping de teste imediato para confirmar que tudo funciona
 echo ""

install_systemd.sh

@@ -2,17 +2,17 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-CONFIG_FILE="${HOME}/.config/health-monitor"
+CONFIG_FILE="${HOME}/.config/health-check"
 
 mkdir -p "${HOME}/.config/systemd/user"
-cp "${SCRIPT_DIR}/systemd/health-monitor.service" "${HOME}/.config/systemd/user/"
-cp "${SCRIPT_DIR}/systemd/health-monitor.timer" "${HOME}/.config/systemd/user/"
+cp "${SCRIPT_DIR}/systemd/health-check.service" "${HOME}/.config/systemd/user/"
+cp "${SCRIPT_DIR}/systemd/health-check.timer" "${HOME}/.config/systemd/user/"
 
 echo "Arquivos de unit systemd copiados para ~/.config/systemd/user/."
 
 systemctl --user daemon-reload
-systemctl --user enable --now health-monitor.timer
-systemctl --user status --no-pager health-monitor.timer
+systemctl --user enable --now health-check.timer
+systemctl --user status --no-pager health-check.timer
 
 # Ping de teste imediato para confirmar que tudo funciona
 echo ""

pyproject.toml

@@ -1,3 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "health-check"
+version = "1.0.2"
+description = "Lightweight Healthchecks.io ping client with opinionated payload (agent, device, ips, uptime)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = []
+
+[project.scripts]
+health-check = "healthcheck:main"
+
 [tool.ruff]
 target-version = "py39"
 line-length = 110
@@ -13,8 +29,8 @@ select = [
     "SIM", # flake8-simplify
 ]
 ignore = [
-    "B904", # raise from exc — não obrigatório em scripts simples
+    "B904",
 ]
 
 [tool.ruff.lint.isort]
-known-first-party = ["healthcheck"]
+known-first-party = ["health_check"]

setup.fish

@@ -1,8 +1,8 @@
 #!/usr/bin/env fish
 
 set REPO_URL "https://github.com/SantosFC/health-check.git"
-set INSTALL_DIR "$HOME/src/health-monitor"
-set CONFIG_FILE "$HOME/.config/health-monitor"
+set INSTALL_DIR "$HOME/src/health-check"
+set CONFIG_FILE "$HOME/.config/health-check"
 
 # 1. Verificar pré-requisitos
 for cmd in git python3 systemctl loginctl
@@ -36,25 +36,30 @@ except Exception as e:
     end
 end
 
-# 4. Clonar ou atualizar repositório
+# 4. Capturar nome do device
+if not set -q DEVICE_NAME
+    read -P "Nome do device: " DEVICE_NAME
+end
+
+# 5. Clonar ou atualizar repositório
 if test -d "$INSTALL_DIR/.git"
     git -C $INSTALL_DIR pull --ff-only
 else
     git clone $REPO_URL $INSTALL_DIR
 end
 
-# 5. Salvar configuração (confirmando antes de sobrescrever)
+# 6. Salvar configuração (confirmando antes de sobrescrever)
 if test -f $CONFIG_FILE
     echo "Configuração existente encontrada em $CONFIG_FILE."
     read -P "Deseja substituir? [s/N] " confirm
     if string match -qi 's' $confirm
-        echo "HEALTHCHECK_URL=$HEALTHCHECK_URL" > $CONFIG_FILE
+        printf "HEALTHCHECK_URL=%s\nDEVICE_NAME=%s\n" $HEALTHCHECK_URL $DEVICE_NAME > $CONFIG_FILE
         echo "Configuração salva em $CONFIG_FILE."
     else
         echo "Configuração mantida. Prosseguindo com valor existente."
     end
 else
-    echo "HEALTHCHECK_URL=$HEALTHCHECK_URL" > $CONFIG_FILE
+    printf "HEALTHCHECK_URL=%s\nDEVICE_NAME=%s\n" $HEALTHCHECK_URL $DEVICE_NAME > $CONFIG_FILE
     echo "Configuração salva em $CONFIG_FILE."
 end
 

setup.sh

@@ -2,8 +2,8 @@
 set -euo pipefail
 
 REPO_URL="https://github.com/SantosFC/health-check.git"
-INSTALL_DIR="${HOME}/src/health-monitor"
-CONFIG_FILE="${HOME}/.config/health-monitor"
+INSTALL_DIR="${HOME}/src/health-check"
+CONFIG_FILE="${HOME}/.config/health-check"
 
 # 1. Verificar pré-requisitos
 for cmd in git python3 systemctl loginctl; do
@@ -31,25 +31,30 @@ except Exception as e:
     [[ "$confirm" =~ ^[sS]$ ]] || { echo "Instalação cancelada."; exit 1; }
 fi
 
-# 4. Clonar ou atualizar repositório
+# 4. Capturar nome do device
+if [[ -z "${DEVICE_NAME:-}" ]]; then
+    read -rp "Nome do device: " DEVICE_NAME </dev/tty
+fi
+
+# 5. Clonar ou atualizar repositório
 if [[ -d "${INSTALL_DIR}/.git" ]]; then
     git -C "${INSTALL_DIR}" pull --ff-only
 else
     git clone "${REPO_URL}" "${INSTALL_DIR}"
 fi
 
-# 5. Salvar configuração (confirmando antes de sobrescrever)
+# 6. Salvar configuração (confirmando antes de sobrescrever)
 if [[ -f "${CONFIG_FILE}" ]]; then
     echo "Configuração existente encontrada em ${CONFIG_FILE}."
     read -rp "Deseja substituir? [s/N] " confirm </dev/tty
     if [[ ! "$confirm" =~ ^[sS]$ ]]; then
         echo "Configuração mantida. Prosseguindo com valor existente."
     else
-        echo "HEALTHCHECK_URL=${HEALTHCHECK_URL}" > "${CONFIG_FILE}"
+        printf "HEALTHCHECK_URL=%s\nDEVICE_NAME=%s\n" "${HEALTHCHECK_URL}" "${DEVICE_NAME}" > "${CONFIG_FILE}"
         echo "Configuração salva em ${CONFIG_FILE}."
     fi
 else
-    echo "HEALTHCHECK_URL=${HEALTHCHECK_URL}" > "${CONFIG_FILE}"
+    printf "HEALTHCHECK_URL=%s\nDEVICE_NAME=%s\n" "${HEALTHCHECK_URL}" "${DEVICE_NAME}" > "${CONFIG_FILE}"
     echo "Configuração salva em ${CONFIG_FILE}."
 fi
 

systemd/health-check.service

@@ -1,12 +1,12 @@
 [Unit]
-Description=Health Monitor check script
+Description=Health check script
 Wants=network-online.target
 After=network-online.target
 
 [Service]
 Type=oneshot
-EnvironmentFile=-%h/.config/health-monitor
-ExecStart=/usr/bin/env python3 %h/src/health-monitor/healthcheck.py
+EnvironmentFile=-%h/.config/health-check
+ExecStart=/usr/bin/env python3 %h/src/health-check/healthcheck.py
 StandardOutput=journal
 StandardError=journal
 

systemd/health-check.timer

@@ -1,5 +1,5 @@
 [Unit]
-Description=Run Health Monitor check every 2 minutes
+Description=Run health check every 2 minutes
 
 [Timer]
 OnCalendar=*:0/2