# Heartbeat

[Open dashboard](https://my.tuna.am/monitors)

The Heartbeat monitor is designed to track regular signals from services running in closed networks, IoT devices or background processes.

***

## How it works

1. You create a Heartbeat monitor and set the expected signal interval
2. Your application periodically sends a `ping` signal
3. If no signal arrives within the configured time — a notification is sent

***

## Parameters

### Description

| Parameter       | Description                   | Required |
| --------------- | ----------------------------- | -------- |
| **Name**        | Unique monitor name           | Yes      |
| **Description** | A note about the task purpose | No       |

![screenshot with monitor description](/docs/img/monitors/description.png)

### Details

Specify the expected interval between jobs and optionally the maximum execution time.

![screenshot with details of the heartbeat monitor](/docs/img/monitors/details_heartbeat.png) ![screenshot with details of the heartbeat monitor](/docs/img/monitors/cron_heartbeat.png)

#### Interval

Two types of schedule are supported:

**Interval**

Expected interval between signals:

| Value      | Description                      |
| ---------- | -------------------------------- |
| 1 minute   | Signal expected every minute     |
| 5 minutes  | Signal expected every 5 minutes  |
| 15 minutes | Signal expected every 15 minutes |
| 30 minutes | Signal expected every 30 minutes |
| 60 minutes | Signal expected every hour       |

**Cron expression**

For irregular schedules use a [Cron expression](https://en.wikipedia.org/wiki/Cron):

```shell
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6)
│ │ │ │ │
* * * * *

```

**Examples:**

| Expression       | Description                         |
| ---------------- | ----------------------------------- |
| `*/5 * * * *`    | Every 5 minutes                     |
| `0 * * * *`      | Every hour                          |
| `0 9-18 * * 1-5` | Every hour from 9 to 18 on weekdays |

### Notifications

The Heartbeat monitor sends notifications in the following cases:

| Reason          | Description                                   |
| --------------- | --------------------------------------------- |
| **Not Running** | The job did not start within the Grace Period |
| **Recovery**    | The job recovered after an error              |

Here you can specify contact groups for notifications. If left unspecified, the user's email is used.

You can also set a waiting period — **Grace Period**. It is added to the expected time of the next signal. For example, if the interval is 5 minutes and the Grace Period is 2 minutes, the alert will be sent 7 minutes after the last signal. Repeated notifications remind you of the problem; you can set the interval and number of these reminders.

![screenshot with monitor job details](/docs/img/monitors/notify.png)

***

## Usage

### Through the CLI

```bash
# Simple ping
tuna monitor ping MONITOR_ID

# With explicit host (useful for identifying the source)
tuna monitor ping MONITOR_ID --host=server-01

# With a message
tuna monitor ping MONITOR_ID --message="All systems operational"

```

### Via HTTP

In addition to the tuna CLI, you can send signals directly via HTTP requests. This is useful when the CLI is unavailable or when you use other programming languages.

**URL format:**

```shell
https://monitor.tuna.am/{MONITOR_ID}/{slug-name}

```

tip

`{slug-name}` is optional and is mainly used for easy identification of the monitor in code.

**curl**

```bash
# Simple ping
curl -s "https://monitor.tuna.am/MONITOR_ID/test"

# With explicit status
curl -s "https://monitor.tuna.am/MONITOR_ID/test?state=ping"
curl -s "https://monitor.tuna.am/MONITOR_ID/test?state=start"
curl -s "https://monitor.tuna.am/MONITOR_ID/test?state=finish"
curl -s "https://monitor.tuna.am/MONITOR_ID/test?state=fail"

# With a message (proper UTF-8 encoding)
curl -G "https://monitor.tuna.am/MONITOR_ID/test" \
  --data-urlencode "message=Backup completed successfully"

# With host and message
curl -G "https://monitor.tuna.am/MONITOR_ID/test?host=server-01" \
  --data-urlencode "message=All systems operational"

```

**wget**

```bash
# Simple ping
wget -qO- "https://monitor.tuna.am/MONITOR_ID/test"

# With parameters
wget -qO- "https://monitor.tuna.am/MONITOR_ID/test?state=ping&host=server-01"

```

**Python**

```python
import requests
from urllib.parse import urlencode

MONITOR_ID = "your_monitor_id"
BASE_URL = f"https://monitor.tuna.am/{ENDPOINT_TOKEN}"

# Simple ping
requests.get(BASE_URL)

# With parameters
params = {
    "state": "ping",
    "host": "server-01",
    "message": "Task completed successfully"
}
requests.get(BASE_URL, params=params)

```

**PowerShell**

```powershell
# Simple ping
Invoke-WebRequest -Uri "https://monitor.tuna.am/MONITOR_ID/test" -Method GET

# With parameters
$params = @{
    state = "ping"
    host = "server-01"
    message = "Backup completed"
}
$uri = "https://monitor.tuna.am/MONITOR_ID/test"
Invoke-WebRequest -Uri $uri -Method GET -Body $params

```

#### Request parameters

| Parameter | Description                                              |
| --------- | -------------------------------------------------------- |
| `state`   | Signal status: `ping`, `start`, `finish`, `fail`         |
| `host`    | Host identifier (useful when there are multiple sources) |
| `message` | Arbitrary message                                        |

### In a systemd service

```ini
# /etc/systemd/system/my-heartbeat.service
[Unit]
Description=Heartbeat ping to Tuna
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/tuna monitor ping MONITOR_ID

[Install]
WantedBy=multi-user.target

```

```ini
# /etc/systemd/system/my-heartbeat.timer
[Unit]
Description=Run heartbeat every 5 minutes

[Timer]
OnBootSec=1min
OnUnitActiveSec=5min

[Install]
WantedBy=timers.target

```

```bash
systemctl enable --now my-heartbeat.timer

```

### In crontab

```bash
# Heartbeat every 5 minutes
*/5 * * * * /usr/local/bin/tuna monitor ping MONITOR_ID

```

***

## Statuses

| Status   | Description                                |
| -------- | ------------------------------------------ |
| **New**  | Monitor created, awaiting the first signal |
| **Up**   | Signals are arriving regularly             |
| **Down** | The signal did not arrive in time          |

***

## Examples

### Monitoring an office GitLab Runner

```bash
# On the GitLab Runner machine
*/5 * * * * /usr/local/bin/tuna monitor ping MONITOR_ID --host=gitLab-runner-0

```

### Monitoring a VPN connection

```bash
#!/bin/bash
# Check the VPN channel and send a heartbeat only if the connection is up

ping -c 1 192.168.14.88 && tuna monitor ping MONITOR_ID --message="VPN is up"


```