# Задача (Job)

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

Задача/Job - монитор предназначен для отслеживания выполнения периодических задач: backup скриптов, cron задач и других операций по расписанию.

***

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

1. Вы создаёте Job монитор и задаёте расписание выполнения
2. При запуске задачи отправляется сигнал `start`
3. При успешном завершении отправляется сигнал `finish`
4. При ошибке отправляется сигнал `fail`
5. Система отслеживает своевременность запуска и время выполнения

***

## Параметры

### Описание

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

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

### Детали

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

![скриншот с деталями job монитора](/docs/img/monitors/details_job.png) ![скриншот с деталями job монитора](/docs/img/monitors/cron_job.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 по будням |

#### Время выполнения

Максимальная длительность задачи **Running Time** - если задача выполняется дольше указанного времени, отправляется уведомление.

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

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

| Причина          | Описание                                                        |
| ---------------- | --------------------------------------------------------------- |
| **Fail**         | Задача завершилась с ошибкой (сигнал `fail` или exit code != 0) |
| **Not Running**  | Задача не запустилась в течение Grace Period                    |
| **Long Running** | Задача выполняется дольше Running Time                          |
| **Recovery**     | Задача восстановилась после ошибки                              |

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

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

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

***

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

### Через CLI (рекомендуется)

Команда `tuna monitor exec` автоматически отправляет сигналы `start`, `finish` или `fail`:

```bash
tuna monitor exec MONITOR_ID -- ./backup.sh

```

Если вы хотите контролировать сигналы вручную:

```bash
# Начало выполнения
tuna monitor ping MONITOR_ID --state=start

# Выполнение вашей задачи
./your-task.sh

# Успешное завершение
tuna monitor ping MONITOR_ID --state=finish

# Или ошибка
tuna monitor ping MONITOR_ID --state=fail

```

### Через 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` | Произвольное сообщение                                  |

Подробнее: [Работа с мониторами в CLI](https://tuna.am/docs/monitors/cli.md)

***

## Статусы

| Статус      | Описание                                                |
| ----------- | ------------------------------------------------------- |
| **New**     | Монитор создан, ожидается первый запуск                 |
| **Running** | Задача выполняется (получен сигнал `start`)             |
| **Up**      | Задача успешно завершена (получен сигнал `finish`)      |
| **Down**    | Задача завершилась с ошибкой или не запустилась вовремя |

***

## Логирование

При использовании `tuna monitor exec` система автоматически захватывает stdout и stderr вашей задачи. Логи можно просмотреть в интерфейсе в истории событий монитора.

![скриншот с сообщением в message](/docs/img/monitors/event.png)

Для отключения отправки логов используйте флаг `--no-stdout`:

```bash
tuna monitor exec MONITOR_ID --no-stdout -- ./task.sh

```

***

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

### Backup PostgreSQL

```bash
#!/bin/bash
# /scripts/backup-postgres.sh

tuna monitor exec MONITOR_ID -- pg_dump -U postgres mydb > /backups/mydb_$(date +%Y%m%d).sql

```

### Синхронизация данных

```bash
#!/bin/bash
# /scripts/sync-data.sh

tuna monitor exec MONITOR_ID -- rsync -avz /data/ remote:/backup/data/

```

### Crontab

```bash
# Backup базы данных каждую ночь в 3:00
0 3 * * * tuna monitor exec MONITOR_ID -- /scripts/backup-db.sh

# Очистка логов каждый час
0 * * * * tuna monitor exec MONITOR_ID -- /scripts/cleanup-logs.sh

```