Метрики (custom time-series)

Метрики — это лёгкий способ слать в Notifly произвольные числовые значения (стоимость запроса к LLM, длину очереди, RPS, остаток на балансе, температуру датчика) и получать из них временные ряды с графиками и пороговыми алёртами.

Вы создаёте источник метрик (metric source) — он получает публичный токен с префиксом M — и шлёте на POST /metric/<token> числа с произвольными именами. Метрики создаются автоматически при первом поступлении: заранее ничего объявлять не нужно. Каждая точка раскладывается в три pre-агрегированных бакета (1m, 1h, 1d), которые потом отдаются для графиков.

Удобно для:

• учёта расходов на AI (llm_cost_total, tokens_total) прямо из кода;
• бизнес-метрик (заказы, регистрации, выручка) без отдельной BI-системы;
• IoT / телеметрии (температура, влажность, заряд) с дешёвым HTTP-ingest;
• лёгкой замены Prometheus push-gateway для pet-проектов и cron-скриптов.

Метрики vs мониторы

Активные мониторы сами дёргают ваш ресурс и проверяют его доступность. Метрики — наоборот: значения присылает ваше приложение, а Notifly хранит ряд и срабатывает по порогу. Это push-модель, как у heartbeat, только с числами вместо пинга.

Создание источника метрик

Через админку

1. Откройте app.notifly.ru → Мониторинг → Метрики.
2. Нажмите «Создать источник метрик», заполните:
   • Название — для отображения, например «LLM-расходы» или «Прод-телеметрия».
   • Канал уведомлений — куда слать алёрты по метрикам этого источника (свой канал или расшаренный с правом отправки). Можно оставить «—»: точки будут приниматься, но алёртам некуда будет уходить.
3. После создания токен (M…) и готовые примеры интеграции видны в строке источника — токен понадобится для ingest.

Через REST API

curl -X POST "$NOTIFLY_URL/metric-source" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <api-token>" \
     -d '{
       "name": "LLM-расходы",
       "channelId": 12345
     }'

В ответе придёт объект источника с публичным token (префикс M и 40 hex-символов):

{
  "id": 7,
  "token": "M7c2a8f3b1e0d4a6c8e9f2b1d4c7e0a9b2f5d8c1e",
  "channelId": 12345,
  "name": "LLM-расходы",
  "created": "2026-06-23T10:11:12Z",
  "metricCount": 0,
  "appName": "Marketing"
}

Полный URL для ingest — ${NOTIFLY_URL}/metric/M7c2a8f3b1e0d4a6c8e9f2b1d4c7e0a9b2f5d8c1e.

Токен источника — это право на запись точек

Токен M… источника метрик публичный: он встраивается в код приложения и позволяет только слать точки в этот источник (как токен канала A… для сообщений). Не путайте его с API-токеном — у того тоже префикс M, но это ключ аккаунта. Управление источниками, метриками и алёртами (/metric-source/*) требует API-токена. Перевыпуска у токена источника нет: если он утёк — удалите источник через админку или DELETE /metric-source/:id (вместе с ним удаляются все его метрики, ряды и алёрты), старый URL начнёт тихо отвечать 204 без записи данных.

Отправка точек: POST /metric/:token

Публичный эндпоинт без авторизации (аутентификация — сам токен в URL). Принимает три формата тела (application/json) — выбирайте удобный.

Формат 1 — одно значение

{"name": "queue_depth", "value": 42}

Формат 2 — батч values

Карта «имя → значение». За один запрос обновляете сразу несколько метрик:

{
  "values": {
    "llm_cost_total": 0.42,
    "tokens_total": 1230,
    "queue_depth": 17
  }
}

Поле values толерантно к двум формам JSON: можно прислать объект (как выше) или массив [{"name":"cost","value":0.42}, {"name":"tokens","value":1230}] — элементы без name игнорируются, при повторе имени побеждает последнее значение.

Формат 3 — точки с явным временем points

Для отправки исторических точек или дозаписи задним числом. Каждая точка может нести свой ts:

{
  "points": [
    {"name": "temperature", "value": 21.4, "ts": 1748174400},
    {"name": "temperature", "value": 21.7, "ts": 1748174460},
    {"name": "humidity", "value": 55}
  ]
}

Поле ts — Unix-время числом, секунды или миллисекунды (определяется автоматически по величине):

• Unix-секунды — целое < 1e12, например 1748174400;
• Unix-миллисекунды — целое >= 1e12, например 1748174400000.

Если ts не указан, берётся текущее время сервера (UTC).

Кривые часы клиента не ломают ряд

ts вне окна [now − 365 дней, now + 5 минут] не отклоняет запрос, а клампится к границе окна: будущее дальше +5 мин превращается в now, прошлое дальше −365 дней — в now − 365 дней. Так один рассинхронизированный таймстемп не засоряет хранилище и не портит lastValue.

Все три формата можно комбинировать в одном запросе — точки из name/value, values и points объединяются в общий список.

Ответ и квота

Эндпоинт возвращает 204 No Content при успехе. Если в теле нет точек (например {}) или токен неизвестен — тоже 204 (тихо игнорируется). При превышении дневной квоты событий — 429 (точки не записываются, владельцу приходит уведомление о квоте); 429 с заголовком Retry-After возможен и при слишком частых запросах. Невалидный JSON, битое имя метрики, нечисловое значение или больше 500 точек дают 400.

1 запрос = 1 событие квоты

Списывается одно событие за весь запрос, независимо от числа точек в батче. То есть батч из 100 метрик стоит столько же, сколько одна метрика — выгодно собирать значения и слать их пачкой. Дневной лимит событий зависит от тарифа (Free — 1 000, Pro — 100 000, Business — без практического лимита), см. Квоты и тарифы.

Лимиты ingest

Ограничение	Значение
Максимум точек в одном запросе	500
Размер тела запроса	до 64 КиБ
Максимум уникальных метрик в источнике	100 (точки новых метрик сверх лимита тихо пропускаются)
Имя метрики	regex ^[a-zA-Z0-9_\-\.]{1,64}$ — латиница, цифры, _, -, ., до 64 символов
Значение	конечное число (не NaN, не ±Inf)

Запрос с битым именем метрики или нечисловым значением целиком отклоняется с 400 и понятным описанием ошибки.

Примеры по языкам

# curl — одно значение
curl -X POST "$NOTIFLY_URL/metric/M7c2a8f3b1e0d4a6c8e9f2b1d4c7e0a9b2f5d8c1e" \
     -H "Content-Type: application/json" \
     -d '{"name":"llm_cost_total","value":0.0042}'

# curl — батч
curl -X POST "$NOTIFLY_URL/metric/M7c2a8f3b1e0d4a6c8e9f2b1d4c7e0a9b2f5d8c1e" \
     -H "Content-Type: application/json" \
     -d '{"values":{"orders":12,"revenue":3490.5}}'

# Python
import requests
requests.post(
    "https://api.notifly.ru/metric/M7c2a8f3b1e0d4a6c8e9f2b1d4c7e0a9b2f5d8c1e",
    json={"values": {"llm_cost_total": 0.0042, "tokens_total": 1230}},
    timeout=5,
)

// JavaScript / Node
await fetch('https://api.notifly.ru/metric/M7c2a8f3b1e0d4a6c8e9f2b1d4c7e0a9b2f5d8c1e', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'queue_depth', value: 42}),
});

// Go
body := strings.NewReader(`{"name":"queue_depth","value":42}`)
http.Post("https://api.notifly.ru/metric/M7c2a8f3b1e0d4a6c8e9f2b1d4c7e0a9b2f5d8c1e",
    "application/json", body)

Тип метрики: gauge vs counter

У каждой метрики есть тип, влияющий на визуализацию по умолчанию:

Тип	Смысл	Как рисуется
gauge	моментальное значение, которое колеблется вверх-вниз (температура, длина очереди, баланс)	по last / avg бакета
counter	монотонно растущий счётчик (всего запросов, суммарная стоимость)	акцент на sum за период

Тип определяется автоматически по имени при создании метрики (конвенция в духе Prometheus): если имя оканчивается на _total, _count, _sum или _counter — это counter, иначе gauge. Например llm_cost_total → counter, queue_depth → gauge.

Если авто-определение ошиблось, тип можно переопределить через API — PATCH /metric-source/:id/metrics/:mid:

curl -X PATCH "$NOTIFLY_URL/metric-source/7/metrics/31" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <api-token>" \
     -d '{"type":"gauge"}'

Допустимы только значения gauge и counter — иначе 400.

Хранение и временные ряды

Каждая точка при поступлении раскладывается сразу в три бакета — 1m, 1h, 1d. В каждом бакете накапливаются sum, count, min, max и last (последнее по времени значение). У бакетов разный срок хранения (TTL):

Бакет	Гранулярность	Хранится
1m	поминутно	24 часа
1h	почасово	30 дней
1d	посуточно	365 дней

В админке

Страница источника показывает его метрики (последнее значение, время, число точек) и график выбранной метрики за период от 10 минут до года (10m … 1y; для 10m и 1h есть живой режим Live). Отметьте две и больше метрики — появится общий график для сравнения.

Чтение ряда — GET .../series

curl "$NOTIFLY_URL/metric-source/7/metrics/31/series?bucket=1h&from=2026-06-22T00:00:00Z&to=2026-06-23T00:00:00Z" \
     -H "X-Notifly-Key: <api-token>"

Параметры:

Параметр	Значение	По умолчанию
bucket	1m, 1h или 1d	1h
from, to	границы интервала, RFC3339	последние 24 часа

Неизвестный bucket даёт 400; нераспознанные from/to молча заменяются значениями по умолчанию.

Ответ — массив бакетов; фронт сам решает, что рисовать (last для gauge, sum для counter):

[
  {"ts": "2026-06-22T10:00:00Z", "sum": 4.2, "count": 60, "min": 0.01, "max": 0.21, "last": 0.07},
  {"ts": "2026-06-22T11:00:00Z", "sum": 3.9, "count": 58, "min": 0.01, "max": 0.18, "last": 0.05}
]

Если запрошенный бакет пуст (например, 1d ещё не успел накопиться), но поминутные данные есть, Notifly агрегирует на лету из 1m-бакетов.

Алёрты по порогу

Алёрт — это правило «если значение метрики удовлетворяет условию — отправить уведомление в канал источника». Пороги только статические: детекции аномалий, сравнения с прошлым периодом и скорости изменения нет. Правило проверяется при каждом поступлении точек — по финальному (самому позднему по ts) значению метрики в запросе, чтобы батч из сотен точек не плодил дубли уведомлений.

Поля алёрта:

Поле	Описание
metricName	имя метрики, к которой применяется правило (обязательное, иначе 400)
operator	оператор сравнения: >, >=, <, <=, == (обязательное)
threshold	пороговое значение (число)
title	заголовок уведомления; если пусто — генерируется автоматически (⚠️ <metric> <op> <threshold>)
cooldownMinutes	минимальный интервал между уведомлениями этого правила; 0 → 60 минут

Канал в алёрте не задаётся — он берётся из источника метрик (поле channelId источника); присланный в теле channelId игнорируется. Канал фиксируется в правиле при его создании и сохранении: если потом сменить канал источника, пересохраните алёрты. У источника без канала алёрты не доставляются.

В админке алёрт добавляется на странице источника («Добавить алерт»), имя метрики выбирается из уже поступивших. Через API правило можно завести и заранее, на метрику, которой ещё нет.

# Алёрт: расходы на LLM за сутки превысили $50
curl -X POST "$NOTIFLY_URL/metric-source/7/alerts" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <api-token>" \
     -d '{
       "metricName": "llm_cost_total",
       "operator": ">",
       "threshold": 50,
       "title": "LLM-расходы превысили $50",
       "cooldownMinutes": 360
     }'

При срабатывании в канал источника прилетит обычное сообщение с текстом вида:

llm_cost_total = 51.3

Источник: LLM-расходы

Порог: > 50

Приоритет сообщения — приоритет канала по умолчанию. Как и любое сообщение канала, оно эскалируется по настроенным методам доставки, подчиняется тихим часам и в активном окне обслуживания канала приходит беззвучно.

Cooldown спасает от спама

Пока активен cooldown (по умолчанию час), повторные срабатывания того же правила не шлют новых уведомлений. Состояния «сработал / вернулся в норму» у правила нет: пока значения остаются за порогом, уведомление повторяется не чаще раза в cooldown, а уведомления о возврате в норму не бывает. Для метрик, которые «дребезжат» у порога, ставьте cooldown побольше.

REST API

Публичный ingest-эндпоинт не требует авторизации (токен источника в URL). Все остальные требуют API-токен (X-Notifly-Key); операции записи — с правом write.

Метод и путь	Авторизация	Назначение
POST /metric/:token	публичный (токен источника)	отправить точки (три формата)
GET /metric-source	API-токен	список источников
POST /metric-source	API-токен (write)	создать источник
PUT /metric-source/:id	API-токен (write)	обновить (название, канал)
DELETE /metric-source/:id	API-токен (write)	удалить источник
GET /metric-source/:id/metrics	API-токен	список метрик источника
PATCH /metric-source/:id/metrics/:mid	API-токен	сменить тип (gauge/counter)
DELETE /metric-source/:id/metrics/:mid	API-токен (write)	удалить метрику
GET /metric-source/:id/metrics/:mid/series	API-токен	временной ряд (бакеты)
GET /metric-source/:id/alerts	API-токен	список алёртов
POST /metric-source/:id/alerts	API-токен (write)	создать алёрт
PUT /metric-source/:id/alerts/:aid	API-токен (write)	обновить алёрт
DELETE /metric-source/:id/alerts/:aid	API-токен (write)	удалить алёрт

Отправка точек и управление источниками, метриками и алёртами есть и в Go и Python SDK (PushMetric/PushMetrics, push_metric/push_metrics).

Смежные возможности: Активные мониторы, Heartbeat.