mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-08-27 20:40:13 +03:00
177 lines
4.9 KiB
Markdown
177 lines
4.9 KiB
Markdown
# Statistics API
|
|
|
|
## `GET /statistics`
|
|
|
|
Returns aggregated server statistics including compute resources, projects, nodes, and links.
|
|
|
|
**Authentication:** Requires active user session
|
|
|
|
**Method:** `GET`
|
|
|
|
**URL:** `http://server:3080/v1/statistics`
|
|
|
|
### Response
|
|
|
|
```json
|
|
{
|
|
"computes": [
|
|
{
|
|
"compute_id": "string",
|
|
"compute_name": "string",
|
|
"statistics": {
|
|
"memory_total": 16777216000,
|
|
"memory_free": 8000000000,
|
|
"memory_used": 8777216000,
|
|
"swap_total": 2147479552,
|
|
"swap_free": 1500000000,
|
|
"swap_used": 647279552,
|
|
"cpu_usage_percent": 45,
|
|
"memory_usage_percent": 52,
|
|
"swap_usage_percent": 30,
|
|
"disk_usage_percent": 67,
|
|
"load_average_percent": [12, 8, 5]
|
|
}
|
|
}
|
|
],
|
|
"projects": {
|
|
"total": 5,
|
|
"opened": 3,
|
|
"closed": 2
|
|
},
|
|
"nodes": {
|
|
"total": 42,
|
|
"open_project_nodes": 30,
|
|
"closed_project_nodes": 12,
|
|
"by_type": {
|
|
"qemu": 20,
|
|
"docker": 12,
|
|
"dynamips": 6,
|
|
"vpcs": 4
|
|
},
|
|
"by_status": {
|
|
"started": 25,
|
|
"stopped": 12,
|
|
"suspended": 5
|
|
}
|
|
},
|
|
"links": {
|
|
"total": 38,
|
|
"capturing": 2
|
|
}
|
|
}
|
|
```
|
|
|
|
### Field Descriptions
|
|
|
|
#### `computes`
|
|
|
|
Array of compute node statistics. Each compute reports:
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `compute_id` | string | Unique identifier for the compute |
|
|
| `compute_name` | string | Human-readable name |
|
|
| `statistics` | object | Resource usage statistics |
|
|
|
|
#### `computes[].statistics`
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `memory_total` | integer | Total physical memory in bytes |
|
|
| `memory_free` | integer | Free memory in bytes |
|
|
| `memory_used` | integer | Used memory in bytes |
|
|
| `swap_total` | integer | Total swap space in bytes |
|
|
| `swap_free` | integer | Free swap space in bytes |
|
|
| `swap_used` | integer | Used swap space in bytes |
|
|
| `cpu_usage_percent` | integer | CPU usage percentage (0-100) |
|
|
| `memory_usage_percent` | integer | Memory usage percentage (0-100) |
|
|
| `swap_usage_percent` | integer | Swap usage percentage (0-100) |
|
|
| `disk_usage_percent` | integer | Disk usage percentage for project directory (0-100) |
|
|
| `load_average_percent` | integer[] | Load average as percentage per CPU core (1/5/15 min) |
|
|
|
|
#### `projects`
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `total` | integer | Total number of projects |
|
|
| `opened` | integer | Number of projects currently opened |
|
|
| `closed` | integer | Number of projects currently closed |
|
|
|
|
#### `nodes`
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `total` | integer | Total number of nodes across all projects |
|
|
| `open_project_nodes` | integer | Nodes in opened projects (has real status) |
|
|
| `closed_project_nodes` | integer | Nodes in closed projects (loaded from topology JSON, no status) |
|
|
| `by_type` | object | Node count grouped by node type (qemu, docker, dynamips, etc.) |
|
|
| `by_status` | object | Node count grouped by status (only for `open_project_nodes`) |
|
|
|
|
**Note on `by_status`:** Status is a runtime attribute only available for nodes in opened projects. Closed projects store topology data in JSON format which does not include runtime status. Therefore `by_status` only reflects nodes from opened projects.
|
|
|
|
Valid node statuses: `started`, `stopped`, `suspended`
|
|
|
|
#### `links`
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `total` | integer | Total number of links across all projects |
|
|
| `capturing` | integer | Number of links currently capturing packets |
|
|
|
|
### Example Usage
|
|
|
|
```bash
|
|
# Get statistics
|
|
curl -X GET http://localhost:3080/v1/statistics \
|
|
-H "Authorization: Bearer <token>"
|
|
```
|
|
|
|
### Dashboard Integration
|
|
|
|
This API is designed for monitoring dashboards that need:
|
|
|
|
- **System health**: CPU, memory, disk from `computes[].statistics`
|
|
- **Project overview**: Project counts from `projects`
|
|
- **Node inventory**: Node counts by type and status from `nodes`
|
|
- **Capture monitoring**: Active capture sessions from `links.capturing`
|
|
|
|
### Error Responses
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| 401 | Unauthorized - invalid or missing session |
|
|
| 500 | Internal server error |
|
|
|
|
### Future Optimizations
|
|
|
|
#### Per-Compose Node Statistics
|
|
|
|
Currently `nodes` are aggregated globally. Future enhancement could add per-compute breakdown:
|
|
|
|
```json
|
|
"nodes": {
|
|
"total": 42,
|
|
"by_compute": {
|
|
"local": {
|
|
"total": 30,
|
|
"open_project_nodes": 20,
|
|
"closed_project_nodes": 10,
|
|
"by_type": { "qemu": 20, "docker": 10 }
|
|
},
|
|
"remote-server-1": {
|
|
"total": 12,
|
|
"open_project_nodes": 10,
|
|
"closed_project_nodes": 2,
|
|
"by_type": { "docker": 12 }
|
|
}
|
|
},
|
|
"by_type": { "qemu": 20, "docker": 22 },
|
|
"open_project_nodes": 30,
|
|
"closed_project_nodes": 12,
|
|
"by_type": { "qemu": 20, "docker": 22 },
|
|
"by_status": { "started": 25, "stopped": 12, "suspended": 5 }
|
|
}
|
|
```
|
|
|
|
This requires tracking which compute each node runs on (Node._compute).
|