Документация НетПульс

Полный справочник по REST API, установке агентов и интеграциям. Версия API: v1. Базовый URL: https://api.netpulse.ru/v1.

Быстрый старт: Если вы хотите немедленно развернуть первый агент, перейдите к разделу Установка агента.

Обзор платформы

НетПульс — распределённая система сбора сетевых метрик. Архитектура состоит из трёх компонентов:

Агент (netpulse-agent) — лёгкий демон (~8 МБ RAM), работает на хосте клиента. Устанавливает постоянное TLS-соединение с коллектором и периодически отправляет heartbeat и результаты проверок.
Коллектор — наш облачный сервер, принимающий входящие соединения от агентов (порт 443, TLS 1.3). Именно сюда агенты подключаются в фоне.
REST API — HTTP API для управления агентами, получения метрик и настройки алертов из ваших систем.

Важно: Агенты непрерывно поддерживают TLS-соединение с коллектором. Это нормально — так работает механизм real-time метрик. Каждая проверка создаёт отдельный короткоживущий TCP-сеанс для измерения латентности рукопожатия.

Установка агента

Агент поддерживает Linux (deb/rpm/binary), Windows и macOS. Рекомендуется установка через пакетный менеджер.

Linux (Debian / Ubuntu)

bash

# Добавить репозиторий
curl -fsSL https://repo.netpulse.ru/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/netpulse.gpg
echo "deb [signed-by=/usr/share/keyrings/netpulse.gpg] https://repo.netpulse.ru/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/netpulse.list

# Установить
sudo apt update && sudo apt install -y netpulse-agent

# Зарегистрировать агент (замените TOKEN на ваш API-ключ)
sudo netpulse-agent register --token npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Запустить как системный сервис
sudo systemctl enable --now netpulse-agent

Linux (RHEL / CentOS / Fedora)

bash

sudo rpm --import https://repo.netpulse.ru/gpg.key
sudo tee /etc/yum.repos.d/netpulse.repo <<EOF
[netpulse]
name=NetPulse Agent Repository
baseurl=https://repo.netpulse.ru/rpm
enabled=1
gpgcheck=1
EOF
sudo dnf install -y netpulse-agent
sudo netpulse-agent register --token npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
sudo systemctl enable --now netpulse-agent

Windows (PowerShell, от администратора)

powershell

# Скачать инсталлятор
Invoke-WebRequest -Uri "https://download.netpulse.ru/windows/netpulse-agent-setup.exe" `
  -OutFile "netpulse-agent-setup.exe"

# Тихая установка
.\netpulse-agent-setup.exe /S /TOKEN=npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Агент запускается как Windows Service автоматически

Docker

bash

docker run -d \
  --name netpulse-agent \
  --restart unless-stopped \
  --network host \
  -e NETPULSE_TOKEN=npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -e NETPULSE_LABEL="prod-server-1" \
  ghcr.io/netpulse/agent:latest

Быстрый старт

Создайте аккаунт на netpulse.ru и получите API-ключ в разделе «Настройки → API».
Установите агент по инструкции выше. После запуска агент появится в дашборде через 30–60 секунд.
Проверьте статус агента через API или в веб-интерфейсе.
Настройте алерты — укажите email или Telegram Bot для получения уведомлений при аномалиях.

Аутентификация

Все запросы к API требуют Bearer-токен. Токен передаётся в заголовке Authorization:

http

Authorization: Bearer npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Получить токен: Личный кабинет → Настройки → API-ключи → «Создать ключ».

Безопасность: Никогда не передавайте токен в URL-параметрах. Используйте только заголовок Authorization. Токены ротируйте не реже раза в 90 дней.

API: Агенты

GET /agents

Возвращает список всех агентов аккаунта.

curl

curl -s -X GET https://api.netpulse.ru/v1/agents \
  -H "Authorization: Bearer npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

json — ответ

{
  "ok": true,
  "data": [
    {
      "id": "agt_a1b2c3d4e5f6",
      "label": "prod-server-1",
      "ip": "192.168.1.10",
      "os": "linux",
      "version": "2.4.1",
      "status": "online",
      "last_seen": "2024-11-14T09:42:17Z",
      "latency_ms": 18,
      "packet_loss": 0.01
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50 }
}

GET /agents/{id}

Детали одного агента по ID.

POST /agents

Зарегистрировать новый агент (вызывается автоматически при netpulse-agent register).

Параметр	Тип	Описание
label	string	Человекочитаемое имя агента
os	string	Операционная система: linux, windows, macos
hostname	string	Hostname хоста
tags	string[]	Произвольные теги для группировки

DELETE /agents/{id}

Удалить агент. Агент прекратит отправлять метрики при следующем heartbeat.

API: Метрики

GET /metrics

Получить временной ряд метрик. Поддерживает фильтрацию по агенту, времени и типу.

curl

curl -s "https://api.netpulse.ru/v1/metrics?agent_id=agt_a1b2c3&from=2024-11-14T00:00:00Z&to=2024-11-14T12:00:00Z&resolution=5m" \
  -H "Authorization: Bearer npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Параметр	Тип	Описание
agent_id	string	Фильтр по ID агента (необязательно)
from	ISO 8601	Начало диапазона
to	ISO 8601	Конец диапазона
resolution	string	Шаг: 30s, 1m, 5m, 1h, 1d
metric	string	latency, packet_loss, jitter, tls_handshake_ms

Протокол связи агента

Агент поддерживает постоянное TLS-соединение с коллектором collector.netpulse.ru:443. Данные передаются в формате протобуф (Protocol Buffers v3) поверх WebSocket / HTTP/2.

TLS-конфигурация

Агент использует следующие параметры TLS для установки соединения:

конфигурация TLS

server_name:    collector.netpulse.ru
tls_versions:   TLSv1.3, TLSv1.2
cipher_suites:  TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384,
                TLS_CHACHA20_POLY1305_SHA256
alpn:           h2, http/1.1
session_tickets: enabled
reconnect_delay: exponential backoff 1s–300s
heartbeat:      every 30s (configurable)

Каждый агент устанавливает одно долгоживущее соединение для стриминга метрик и короткоживущие соединения для каждой активной проверки — это позволяет точно измерять TLS-латентность рукопожатия.

Конфигурация агента

Файл конфигурации расположен в /etc/netpulse/agent.yaml (Linux) или %PROGRAMDATA%\NetPulse\agent.yaml (Windows).

yaml

token: "npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

collector:
  host: "collector.netpulse.ru"
  port: 443
  tls: true
  tls_skip_verify: false

agent:
  label: "my-server"
  tags: ["production", "moscow"]
  check_interval: 30   # секунд
  heartbeat: 30         # секунд

checks:
  ping:
    enabled: true
    targets: ["8.8.8.8", "1.1.1.1", "77.88.8.8"]
  tcp:
    enabled: true
    targets:
      - host: "your-service.company.ru"
        port: 443
  tls:
    enabled: true
    measure_handshake: true
    targets: ["collector.netpulse.ru:443"]

log:
  level: "info"   # debug, info, warn, error
  file: "/var/log/netpulse/agent.log"

Интеграция с Telegram

Создайте Telegram Bot через @BotFather, скопируйте токен и добавьте его в настройках аккаунта. Пример уведомления:

json — Webhook payload

{
  "event": "agent.offline",
  "agent_id": "agt_a1b2c3d4e5f6",
  "label": "prod-server-1",
  "severity": "critical",
  "message": "Агент prod-server-1 недоступен более 2 минут",
  "timestamp": "2024-11-14T09:45:00Z"
}

Webhook

НетПульс может отправлять HTTP POST на ваш endpoint при любом событии. Укажите URL в «Настройки → Уведомления → Webhook».

bash — тест webhook

curl -s -X POST https://api.netpulse.ru/v1/webhooks/test \
  -H "Authorization: Bearer npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"webhook_id": "wh_abc123"}'

Grafana Data Source

НетПульс предоставляет совместимый с Prometheus /metrics endpoint и нативный плагин для Grafana.

bash — prometheus scrape

# prometheus.yml
scrape_configs:
  - job_name: 'netpulse'
    scrape_interval: 30s
    bearer_token: "npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    static_configs:
      - targets: ['api.netpulse.ru:443']
    metrics_path: '/v1/prometheus'
    scheme: https