performance improvements, charts improvements, minor UI improvements
This commit is contained in:
Антон
@@ -1,90 +1,142 @@
|
||||
# OpenVPN Monitor API v2 Documentation
|
||||
# OpenVPN Monitor API v3 Documentation
|
||||
|
||||
Этот API предоставляет доступ к данным мониторинга OpenVPN, включая статус клиентов в реальном времени и исторические данные, хранящиеся в Time Series Database (TSDB).
|
||||
This API provides access to OpenVPN monitoring data, including real-time client status and historical data stored in a Time Series Database (TSDB). It features optimized aggregation for fast visualization.
|
||||
|
||||
**Base URL:** `http://<your-server-ip>:5001/api/v1`
|
||||
|
||||
---
|
||||
|
||||
## 1. Статистика по клиенту (Детальная + История)
|
||||
## 1. Global Analytics (Dashboard)
|
||||
|
||||
Основной эндпоинт для построения графиков и отчетов. Поддерживает динамическую агрегацию данных (умный выбор детализации).
|
||||
Provides aggregated trend data for the entire server. optimized for visualization with exactly **96 data points** regardless of the time range.
|
||||
|
||||
### `GET /stats/<common_name>`
|
||||
### `GET /analytics`
|
||||
|
||||
#### Параметры запроса (Query Parameters)
|
||||
|
||||
| Параметр | Тип | По умолчанию | Описание |
|
||||
#### Query Parameters
|
||||
| Parameter | Type | Default | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `range` | string | `24h` | Период выборки. Поддерживаются форматы: `24h` (часы), `7d` (дни), `30d`, `1y` (годы). |
|
||||
| `resolution` | string | `auto` | Принудительная детализация данных. <br>**Значения:**<br>`auto` — автоматический выбор (см. логику ниже)<br>`raw` — сырые данные (каждые 10-30 сек)<br>`5min` — 5 минут<br>`hourly` — 1 час<br>`6h` — 6 часов<br>`daily` — 1 день |
|
||||
| `range` | string | `24h` | Time range. Supported: `24h`, `7d`, `30d`. |
|
||||
|
||||
#### Логика `resolution=auto`
|
||||
API автоматически выбирает таблицу источника данных в зависимости от длительности диапазона:
|
||||
* **≤ 24 часов:** `usage_history` (Сырые данные)
|
||||
* **≤ 7 дней:** `stats_hourly` (Агрегация по часам)
|
||||
* **≤ 3 месяцев:** `stats_6h` (Агрегация по 6 часов)
|
||||
* **> 3 месяцев:** `stats_daily` (Агрегация по дням)
|
||||
|
||||
#### Пример запроса
|
||||
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=7d
|
||||
|
||||
```
|
||||
|
||||
#### Пример ответа
|
||||
#### Behavior
|
||||
* **24h**: Returns 15-minute intervals.
|
||||
* **7d**: Returns 105-minute intervals (1h 45m).
|
||||
* **30d**: Returns 450-minute intervals (7h 30m).
|
||||
* **Zero-Filling**: Missing data periods are automatically filled with zeros to ensure graph continuity.
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"timestamp": "2026-01-08 14:30:00",
|
||||
"timestamp": "2026-01-09 12:00:00",
|
||||
"range": "24h",
|
||||
"data": {
|
||||
"common_name": "user-alice",
|
||||
"status": "Active",
|
||||
"real_address": "192.168.1.50:54321",
|
||||
"last_activity": "N/A",
|
||||
"current_rates": {
|
||||
"recv_mbps": 1.5,
|
||||
"sent_mbps": 0.2
|
||||
},
|
||||
"totals": {
|
||||
"received_mb": 500.25,
|
||||
"sent_mb": 120.10
|
||||
},
|
||||
"meta": {
|
||||
"resolution_used": "stats_hourly",
|
||||
"start": "2026-01-01 14:30:00",
|
||||
"end": "2026-01-08 14:30:00",
|
||||
"record_count": 168
|
||||
},
|
||||
"history": [
|
||||
"global_history_24h": [
|
||||
{
|
||||
"timestamp": "2026-01-01 15:00:00",
|
||||
"bytes_received": 1048576,
|
||||
"bytes_sent": 524288,
|
||||
"bytes_received_rate_mbps": 0,
|
||||
"bytes_sent_rate_mbps": 0
|
||||
"timestamp": "2026-01-09 11:45:00",
|
||||
"total_rx": 102400,
|
||||
"total_tx": 51200,
|
||||
"active_count": 5
|
||||
},
|
||||
...
|
||||
]
|
||||
],
|
||||
"max_concurrent_24h": 12,
|
||||
"top_clients_24h": [ ... ],
|
||||
"traffic_distribution": { "rx": 1000, "tx": 500 }
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
> **Примечание:** Поля `*_rate_mbps` в массиве `history` возвращают `0` для агрегированных данных (hourly, daily), так как агрегация хранит только суммарный объем трафика.
|
||||
|
||||
---
|
||||
|
||||
## 2. Текущая статистика (Все клиенты)
|
||||
## 2. Client Statistics (Detail + History)
|
||||
|
||||
Возвращает мгновенный снимок состояния всех известных клиентов.
|
||||
Main endpoint for individual client reports. Supports **Dynamic Aggregation** to optimize payload size (~98% reduction for 24h view).
|
||||
|
||||
### `GET /stats/<common_name>`
|
||||
|
||||
#### Query Parameters
|
||||
| Parameter | Type | Default | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `range` | string | `24h` | Time range. Formats: `1h`, `3h`, `6h`, `12h`, `24h`, `7d`, `30d`. |
|
||||
| `resolution` | string | `auto` | Force resolution (optional): `raw`, `5min`, `hourly`, `auto`. |
|
||||
|
||||
#### Dynamic Aggregation Logic (`resolution=auto`)
|
||||
The API automatically selects the aggregation interval based on the requested range to balance detail and performance:
|
||||
|
||||
| Range | Resolution | Points | Source Table |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **1h** | **30 sec** | 120 | `usage_history` (Raw) |
|
||||
| **3h** | **1 min** | 180 | `usage_history` (Raw) |
|
||||
| **6h** | **2 min** | 180 | `usage_history` (Raw) |
|
||||
| **12h** | **5 min** | 144 | `usage_history` (Raw) |
|
||||
| **24h** | **15 min** | 96 | `usage_history` (Raw) |
|
||||
| **7d** | **1 Hour** | 168 | `stats_hourly` |
|
||||
| **30d** | **6 Hours** | 120 | `stats_6h` |
|
||||
|
||||
*All short-term ranges (≤24h) include automatic **Zero-Filling**.*
|
||||
|
||||
#### Examples: Long-Term Aggregated Data
|
||||
|
||||
To explicitly request data from long-term storage tables (skipping raw data), use the `resolution` parameter or specific ranges.
|
||||
|
||||
**1. Last 7 Days (Hourly Resolution)**
|
||||
Uses `stats_hourly` table. Reduced precision for weekly trends.
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=7d
|
||||
```
|
||||
*or explicit resolution:*
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=7d&resolution=hourly
|
||||
```
|
||||
|
||||
**2. Last 30 Days (6-Hour Resolution)**
|
||||
Uses `stats_6h` table. Ideal for monthly volume analysis.
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=30d
|
||||
```
|
||||
|
||||
**3. Last 1 Year (Daily Resolution)**
|
||||
Uses `stats_daily` table. Extremely lightweight for annual reporting.
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=1y&resolution=daily
|
||||
```
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"common_name": "user-alice",
|
||||
"status": "Active",
|
||||
"current_rates": { "recv_mbps": 1.5, "sent_mbps": 0.2 },
|
||||
"totals": { "received_mb": 500.25, "sent_mb": 120.10 },
|
||||
"history": [
|
||||
{
|
||||
"timestamp": "2026-01-09 11:30:00",
|
||||
"bytes_received": 5000,
|
||||
"bytes_sent": 2000,
|
||||
"bytes_received_rate_mbps": 0.5,
|
||||
"bytes_sent_rate_mbps": 0.1
|
||||
},
|
||||
...
|
||||
],
|
||||
"meta": {
|
||||
"resolution_used": "usage_history_hires",
|
||||
"record_count": 120
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Current Statistics (All Clients)
|
||||
|
||||
Returns a snapshot of all known clients.
|
||||
|
||||
### `GET /stats`
|
||||
|
||||
#### Пример ответа
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
@@ -93,110 +145,63 @@ GET /api/v1/stats/user-alice?range=7d
|
||||
{
|
||||
"common_name": "user-alice",
|
||||
"status": "Active",
|
||||
"real_address": "192.168.1.50:54321",
|
||||
"current_recv_rate_mbps": 1.5,
|
||||
"current_sent_rate_mbps": 0.2,
|
||||
"total_received_mb": 500.25,
|
||||
"total_sent_mb": 120.10,
|
||||
"last_activity": "N/A"
|
||||
"total_received_mb": 500.2
|
||||
},
|
||||
{
|
||||
"common_name": "user-bob",
|
||||
"status": "Disconnected",
|
||||
"real_address": null,
|
||||
"current_recv_rate_mbps": 0,
|
||||
"current_sent_rate_mbps": 0,
|
||||
"total_received_mb": 1500.00,
|
||||
"total_sent_mb": 300.00,
|
||||
"last_activity": "2026-01-08 10:00:00"
|
||||
}
|
||||
...
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Системная статистика
|
||||
## 4. System Statistics
|
||||
|
||||
Сводная информация по всему серверу OpenVPN.
|
||||
Aggregated metrics for the Server.
|
||||
|
||||
### `GET /stats/system`
|
||||
|
||||
#### Пример ответа
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"total_clients": 15,
|
||||
"active_clients": 3,
|
||||
"total_bytes_received": 10737418240,
|
||||
"total_bytes_sent": 5368709120,
|
||||
"total_received_gb": 10.0,
|
||||
"total_sent_gb": 5.0
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Сертификаты
|
||||
## 5. Certificates
|
||||
|
||||
Информация о сроках действия SSL сертификатов пользователей.
|
||||
SSL Certificate expiration tracking.
|
||||
|
||||
### `GET /certificates`
|
||||
|
||||
#### Пример ответа
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"file": "user-alice.crt",
|
||||
"common_name": "user-alice",
|
||||
"days_remaining": "360 days",
|
||||
"is_expired": false,
|
||||
"not_after": "Jan 8 12:00:00 2027 GMT"
|
||||
"is_expired": false
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Вспомогательные методы
|
||||
|
||||
### Список клиентов (Упрощенный)
|
||||
|
||||
Используется для заполнения выпадающих списков в интерфейсе.
|
||||
## 6. Utility Methods
|
||||
|
||||
### `GET /clients`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{"common_name": "user-alice", "status": "Active"},
|
||||
{"common_name": "user-bob", "status": "Disconnected"}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Проверка здоровья (Health Check)
|
||||
|
||||
Проверяет доступность базы данных.
|
||||
Simple list of clients (Common Name + Status) for UI dropdowns.
|
||||
|
||||
### `GET /health`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"status": "healthy"
|
||||
}
|
||||
|
||||
```
|
||||
Database connectivity check. Returns `{"status": "healthy"}`.
|
||||
Reference in New Issue
Block a user