gns3-server/docs/features/statistics-api.md

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

{
  "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

# 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:

"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).