# Heartbeat

[Перейти в личный кабинет](https://my.tuna.am/monitors)

Heartbeat - монитор предназначен для отслеживания регулярных сигналов от сервисов, работающих в закрытых сетях, IoT устройств или фоновых процессов.

***

## Принцип работы

1. Вы создаёте Heartbeat монитор и задаёте ожидаемый интервал сигналов
2. Ваше приложение периодически отправляет сигнал `ping`
3. Если сигнал не приходит в течение заданного времени — отправляется уведомление

***

## Параметры

### Описание

| Параметр     | Описание                       | Обязательный |
| ------------ | ------------------------------ | ------------ |
| **Название** | Уникальное имя монитора        | Да           |
| **Описание** | Примечание о назначении задачи | Нет          |

![скриншот с описанием монитора](/docs/img/monitors/description.png)

### Детали

Указываем ожидаемый интервал между задачами и опционально максимальное время выполнения.

![скриншот с деталями heartbeat монитора](/docs/img/monitors/details_heartbeat.png) ![скриншот с деталями heartbeat монитора](/docs/img/monitors/cron_heartbeat.png)

#### Интервал

Поддерживается два типа расписания:

**Интервал**

Ожидаемый интервал между сигналами:

| Значение | Описание                         |
| -------- | -------------------------------- |
| 1 минута | Сигнал ожидается каждую минуту   |
| 5 минут  | Сигнал ожидается каждые 5 минут  |
| 15 минут | Сигнал ожидается каждые 15 минут |
| 30 минут | Сигнал ожидается каждые 30 минут |
| 60 минут | Сигнал ожидается каждый час      |

**Cron выражение**

Для нерегулярных расписаний используйте [Cron-выражение](https://ru.wikipedia.org/wiki/Cron):

```shell
┌───────────── минута (0 - 59)
│ ┌───────────── час (0 - 23)
│ │ ┌───────────── день месяца (1 - 31)
│ │ │ ┌───────────── месяц (1 - 12)
│ │ │ │ ┌───────────── день недели (0 - 6)
│ │ │ │ │
* * * * *

```

**Примеры:**

| Выражение        | Описание                       |
| ---------------- | ------------------------------ |
| `*/5 * * * *`    | Каждые 5 минут                 |
| `0 * * * *`      | Каждый час                     |
| `0 9-18 * * 1-5` | Каждый час с 9 до 18 по будням |

### Уведомления

Задача монитор отправляет уведомления в следующих случаях:

| Причина         | Описание                                     |
| --------------- | -------------------------------------------- |
| **Not Running** | Задача не запустилась в течение Grace Period |
| **Recovery**    | Задача восстановилась после ошибки           |

Здесь можно указать группы контактов для уведомлений, если не указывать, то используется Email пользователя.

Также задаётся период ожидания - **Grace Period**. Добавляется к ожидаемому времени следующего сигнала. Например, если интервал 5 минут и Grace Period 2 минуты, то алерт будет отправлен через 7 минут после последнего сигнала. Повтор уведомлений напоминает о проблеме, можно задать интервал этих напоминаний и их количество.

![скриншот с деталями job монитора](/docs/img/monitors/notify.png)

***

## Использование

### Через CLI

```bash
# Простой ping
tuna monitor ping MONITOR_ID

# С указанием хоста (полезно для идентификации источника)
tuna monitor ping MONITOR_ID --host=server-01

# С сообщением
tuna monitor ping MONITOR_ID --message="All systems operational"

```

### Через HTTP

Помимо tuna cli, можно отправлять сигналы напрямую через HTTP запросы. Это полезно когда CLI недоступен или вы используете другие языки программирования.

**Формат URL:**

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

```

подсказка

`{slug-name}` - опционален и нужен скорее для простой идентификации монитора в коде.

**curl**

```bash
# Простой ping
curl -s "https://monitor.tuna.am/MONITOR_ID/test"

# С указанием статуса
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"

# С сообщением (корректная кодировка UTF-8)
curl -G "https://monitor.tuna.am/MONITOR_ID/test" \
  --data-urlencode "message=Backup completed successfully"

# С указанием хоста и сообщением
curl -G "https://monitor.tuna.am/MONITOR_ID/test?host=server-01" \
  --data-urlencode "message=Все системы работают"

```

**wget**

```bash
# Простой ping
wget -qO- "https://monitor.tuna.am/MONITOR_ID/test"

# С параметрами
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}"

# Простой ping
requests.get(BASE_URL)

# С параметрами
params = {
    "state": "ping",
    "host": "server-01",
    "message": "Задача выполнена успешно"
}
requests.get(BASE_URL, params=params)

```

**PowerShell**

```powershell
# Простой ping
Invoke-WebRequest -Uri "https://monitor.tuna.am/MONITOR_ID/test" -Method GET

# С параметрами
$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

```

#### Параметры запроса

| Параметр  | Описание                                                |
| --------- | ------------------------------------------------------- |
| `state`   | Статус сигнала: `ping`, `start`, `finish`, `fail`       |
| `host`    | Идентификатор хоста (полезно при нескольких источниках) |
| `message` | Произвольное сообщение                                  |

### В systemd сервисе

```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

```

### В crontab

```bash
# Heartbeat каждые 5 минут
*/5 * * * * /usr/local/bin/tuna monitor ping MONITOR_ID

```

***

## Статусы

| Статус   | Описание                                |
| -------- | --------------------------------------- |
| **New**  | Монитор создан, ожидается первый сигнал |
| **Up**   | Сигналы приходят регулярно              |
| **Down** | Сигнал не пришёл в ожидаемое время      |

***

## Примеры использования

### Мониторинг GitLab Runner в офисе

```bash
# На машине с GitLab Runner
*/5 * * * * /usr/local/bin/tuna monitor ping MONITOR_ID --host=gitLab-runner-0

```

### Мониторинг VPN соединения

```bash
#!/bin/bash
# Проверяем VPN канал и отправляем heartbeat только если соединение активно

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


```