diff options
Diffstat (limited to 'docs/api.rst')
| -rw-r--r-- | docs/api.rst | 920 |
1 files changed, 626 insertions, 294 deletions
diff --git a/docs/api.rst b/docs/api.rst index 04d51eb5..a73d9bfa 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,21 +3,33 @@ API (Restfull/JSON) documentation ================================= +This documentation describes the Glances API version 4 (Restfull/JSON) interface. + +For Glances version 3, please have a look on: +``https://github.com/nicolargo/glances/blob/support/glancesv3/docs/api.rst`` + +Run the Glances API server +-------------------------- + The Glances Restfull/API server could be ran using the following command line: .. code-block:: bash # glances -w --disable-webui +It is also ran automatically when Glances is started in Web server mode (-w). + API URL ------- -The default root API URL is ``http://localhost:61208/api/3``. +The default root API URL is ``http://localhost:61208/api/4``. The bind address and port could be changed using the ``--bind`` and ``--port`` command line options. It is also possible to define an URL prefix using the ``url_prefix`` option from the [outputs] section -of the Glances configuration file. The url_prefix should always end with a slash (``/``). +of the Glances configuration file. + +Note: The url_prefix should always end with a slash (``/``). For example: @@ -25,19 +37,31 @@ For example: [outputs] url_prefix = /glances/ -will change the root API URL to ``http://localhost:61208/glances/api/3`` and the Web UI URL to +will change the root API URL to ``http://localhost:61208/glances/api/4`` and the Web UI URL to ``http://localhost:61208/glances/`` +API documentation URL +--------------------- + +The API documentation is embeded in the server and available at the following URL: +``http://localhost:61208/docs#/``. + +WebUI refresh +------------- + +It is possible to change the Web UI refresh rate (default is 2 seconds) using the following option in the URL: +``http://localhost:61208/glances/?refresh=5`` + GET API status -------------- This entry point should be used to check the API status. -It will return nothing but a 200 return code if everything is OK. +It will the Glances version and a 200 return code if everything is OK. Get the Rest API status:: - # curl -I http://localhost:61208/api/3/status + # curl -I http://localhost:61208/api/4/status "HTTP/1.0 200 OK" GET plugins list @@ -45,7 +69,7 @@ GET plugins list Get the plugins list:: - # curl http://localhost:61208/api/3/pluginslist + # curl http://localhost:61208/api/4/pluginslist ["alert", "amps", "cloud", @@ -76,6 +100,7 @@ Get the plugins list:: "smart", "system", "uptime", + "version", "wifi"] GET alert @@ -83,26 +108,62 @@ GET alert Get plugin stats:: - # curl http://localhost:61208/api/3/alert - [[1690293736.0, - -1, - "WARNING", - "MEM", - 77.54053433873582, - 77.54053433873582, - 77.54053433873582, - 77.54053433873582, - 1, - [], - "", - "memory_percent"]] + # curl http://localhost:61208/api/4/alert + [{"avg": 81.2614296446961, + "begin": 1706975961.0, + "count": 1, + "desc": "", + "end": -1, + "max": 81.2614296446961, + "min": 81.2614296446961, + "sort": "memory_percent", + "state": "WARNING", + "sum": 81.2614296446961, + "top": [], + "type": "MEM"}] + +Fields descriptions: + +* **begin**: Begin timestamp of the event (unit is *timestamp*) +* **end**: End timestamp of the event (or -1 if ongoing) (unit is *timestamp*) +* **state**: State of the event (WARNING|CRITICAL) (unit is *string*) +* **type**: Type of the event (CPU|LOAD|MEM) (unit is *string*) +* **max**: Maximum value during the event period (unit is *float*) +* **avg**: Average value during the event period (unit is *float*) +* **min**: Minimum value during the event period (unit is *float*) +* **sum**: Sum of the values during the event period (unit is *float*) +* **count**: Number of values during the event period (unit is *int*) +* **top**: Top 3 processes name during the event period (unit is *list*) +* **desc**: Description of the event (unit is *string*) +* **sort**: Sort key of the top processes (unit is *string*) + +Get a specific field:: + + # curl http://localhost:61208/api/4/alert/begin + {"begin": [1706975961.0]} + +Get a specific item when field matches the given value:: + + # curl http://localhost:61208/api/4/alert/begin/1706975961.0 + {"1706975961.0": [{"avg": 81.2614296446961, + "begin": 1706975961.0, + "count": 1, + "desc": "", + "end": -1, + "max": 81.2614296446961, + "min": 81.2614296446961, + "sort": "memory_percent", + "state": "WARNING", + "sum": 81.2614296446961, + "top": [], + "type": "MEM"}]} GET amps -------- Get plugin stats:: - # curl http://localhost:61208/api/3/amps + # curl http://localhost:61208/api/4/amps [{"count": 0, "countmax": None, "countmin": 1.0, @@ -111,7 +172,7 @@ Get plugin stats:: "refresh": 3.0, "regex": True, "result": None, - "timer": 0.23587393760681152}, + "timer": 0.32085204124450684}, {"count": 0, "countmax": 20.0, "countmin": None, @@ -120,16 +181,26 @@ Get plugin stats:: "refresh": 3.0, "regex": True, "result": None, - "timer": 0.2357802391052246}] + "timer": 0.32070302963256836}] + +Fields descriptions: + +* **name**: AMP name (unit is *None*) +* **result**: AMP result (a string) (unit is *None*) +* **refresh**: AMP refresh interval (unit is *second*) +* **timer**: Time until next refresh (unit is *second*) +* **count**: Number of matching processes (unit is *number*) +* **countmin**: Minimum number of matching processes (unit is *number*) +* **countmax**: Maximum number of matching processes (unit is *number*) Get a specific field:: - # curl http://localhost:61208/api/3/amps/name + # curl http://localhost:61208/api/4/amps/name {"name": ["Dropbox", "Python", "Conntrack", "Nginx", "Systemd", "SystemV"]} Get a specific item when field matches the given value:: - # curl http://localhost:61208/api/3/amps/name/Dropbox + # curl http://localhost:61208/api/4/amps/name/Dropbox {"Dropbox": [{"count": 0, "countmax": None, "countmin": 1.0, @@ -138,19 +209,31 @@ Get a specific item when field matches the given value:: "refresh": 3.0, "regex": True, "result": None, - "timer": 0.23587393760681152}]} + "timer": 0.32085204124450684}]} GET connections --------------- Get plugin stats:: - # curl http://localhost:61208/api/3/connections + # curl http://localhost:61208/api/4/connections {"net_connections_enabled": True, "nf_conntrack_enabled": True} +Fields descriptions: + +* **LISTEN**: Number of TCP connections in LISTEN state (unit is *number*) +* **ESTABLISHED**: Number of TCP connections in ESTABLISHED state (unit is *number*) +* **SYN_SENT**: Number of TCP connections in SYN_SENT state (unit is *number*) +* **SYN_RECV**: Number of TCP connections in SYN_RECV state (unit is *number*) +* **initiated**: Number of TCP connections initiated (unit is *number*) +* **terminated**: Number of TCP connections terminated (unit is *number*) +* **nf_conntrack_count**: Number of tracked connections (unit is *number*) +* **nf_conntrack_max**: Maximum number of tracked connections (unit is *number*) +* **nf_conntrack_percent**: Percentage of tracked connections (unit is *percent*) + Get a specific field:: - # curl http://localhost:61208/api/3/connections/net_connections_enabled + # curl http://localhost:61208/api/4/connections/net_connections_enabled {"net_connections_enabled": True} GET containers @@ -158,81 +241,101 @@ GET containers Get plugin stats:: - # curl http://localhost:61208/api/3/containers - {"containers": [{"Command": ["/portainer"], - "Created": "2022-10-29T14:59:10.266701439Z", - "Id": "3abd51c615968482d9ccff5afc629f267f6dda113ed68b75b432615fae3b49fb", - "Image": ["portainer/portainer-ce:2.9.3"], - "Status": "running", - "Uptime": "an hour", - "cpu": {"total": 0.0}, - "cpu_percent": 0.0, - "engine": "docker", - "io": {"cumulative_ior": 29429760, "cumulative_iow": 2326528}, - "io_r": None, - "io_w": None, - "key": "name", - "memory": {"cache": None, - "limit": 7836184576, - "max_usage": None, - "rss": None, - "usage": 21876736}, - "memory_usage": 21876736, - "name": "portainer", - "network": {"cumulative_rx": 401604, "cumulative_tx": 0}, - "network_rx": None, - "network_tx": None}, - {"Command": ["top"], - "Created": "2023-05-08T15:29:34.918692365+02:00", - "Id": "4b7f732d43e4bc5d92fe5298cba025b550e6a608754c1c38f9a90aaecd46b8f9", - "Image": "["docker.io/library/ubuntu:latest"]", - "Status": "running", - "Uptime": "2 months", - "cpu": {"total": 6.7650116939635326e-06}, - "cpu_percent": 6.7650116939635326e-06, - "engine": "podman", - "io": {"ior": 0.0, "iow": 0.0, "time_since_update": 1}, - "io_r": 0.0, - "io_w": 0.0, - "key": "name", - "memory": {"limit": 7836184576.0, "usage": 1093632.0}, - "memory_usage": 1093632.0, - "name": "frosty_bouman", - "network": {"rx": 0.0, "time_since_update": 1, "tx": 0.0}, - "network_rx": 0.0, - "network_tx": 0.0, - "pod_id": "8d0f1c783def", - "pod_name": "frosty_bouman"}, - {"Command": [], - "Created": "2022-10-22T14:23:03.120912374+02:00", - "Id": "9491515251edcd5bb5dc17205d7ee573c0be96fe0b08b0a12a7e2cea874565ea", - "Image": "["k8s.gcr.io/pause:3.5"]", - "Status": "running", - "Uptime": "2 months", - "cpu": {"total": 3.177554220933258e-10}, - "cpu_percent": 3.177554220933258e-10, - "engine": "podman", - "io": {"ior": 0.0, "iow": 0.0, "time_since_update": 1}, - "io_r": 0.0, - "io_w": 0.0, - "key": "name", - "memory": {"limit": 7836184576.0, "usage": 204800.0}, - "memory_usage": 204800.0, - "name": "8d0f1c783def-infra", - "network": {"rx": 0.0, "time_since_update": 1, "tx": 0.0}, - "network_rx": 0.0, - "network_tx": 0.0, - "pod_id": "8d0f1c783def", - "pod_name": "8d0f1c783def-infra"}], - "version": {}, - "version_podman": {}} + # curl http://localhost:61208/api/4/containers + [{"command": "/portainer", + "cpu": {"total": 0.0}, + "cpu_percent": 0.0, + "created": "2022-10-29T14:59:10.266701439Z", + "engine": "docker", + "id": "3abd51c615968482d9ccff5afc629f267f6dda113ed68b75b432615fae3b49fb", + "image": ["portainer/portainer-ce:2.9.3"], + "io": {"cumulative_ior": 1187840, "cumulative_iow": 2011136}, + "key": "name", + "memory": {"cache": None, + "limit": 7823585280, + "max_usage": None, + "rss": None, + "usage": 17010688}, + "memory_usage": 17010688, + "name": "portainer", + "network": {"cumulative_rx": 2966333, "cumulative_tx": 0}, + "status": "running", + "uptime": "1 weeks"}, + {"command": "top", + "cpu": {"total": 2.918210864825478e-06}, + "cpu_percent": 2.918210864825478e-06, + "created": "2023-12-09T10:45:34.339489876+01:00", + "engine": "podman", + "id": "481d6ffb7eef284d062628cf350bdd9ce0a803db8a2a505d75565ed24322b714", + "image": "docker.io/library/ubuntu:latest", + "io": {"ior": 0.0, "iow": 0.0, "time_since_update": 1}, + "io_rx": 0.0, + "io_wx": 0.0, + "key": "name", + "memory": {"limit": 7823585280.0, "usage": 1236992.0}, + "memory_usage": 1236992.0, + "name": "sad_darwin", + "network": {"rx": 0.0, "time_since_update": 1, "tx": 0.0}, + "network_rx": 0.0, + "network_tx": 0.0, + "pod_id": "8d0f1c783def", + "pod_name": "sad_darwin", + "status": "running", + "uptime": "1 months"}] + +Fields descriptions: + +* **name**: Container name (unit is *None*) +* **id**: Container ID (unit is *None*) +* **image**: Container image (unit is *None*) +* **status**: Container status (unit is *None*) +* **created**: Container creation date (unit is *None*) +* **command**: Container command (unit is *None*) +* **cpu_percent**: Container CPU consumption (unit is *percent*) +* **memory_usage**: Container memory usage (unit is *byte*) +* **io_rx**: Container IO bytes read rate (unit is *bytepersecond*) +* **io_wx**: Container IO bytes write rate (unit is *bytepersecond*) +* **network_rx**: Container network RX bitrate (unit is *bitpersecond*) +* **network_tx**: Container network TX bitrate (unit is *bitpersecond*) +* **uptime**: Container uptime (unit is *None*) +* **engine**: Container engine (Docker and Podman are currently supported) (unit is *None*) +* **pod_name**: Pod name (only with Podman) (unit is *None*) +* **pod_id**: Pod ID (only with Podman) (unit is *None*) + +Get a specific field:: + + # curl http://localhost:61208/api/4/containers/name + {"name": ["portainer", "sad_darwin", "8d0f1c783def-infra"]} + +Get a specific item when field matches the given value:: + + # curl http://localhost:61208/api/4/containers/name/portainer + {"portainer": [{"command": "/portainer", + "cpu": {"total": 0.0}, + "cpu_percent": 0.0, + "created": "2022-10-29T14:59:10.266701439Z", + "engine": "docker", + "id": "3abd51c615968482d9ccff5afc629f267f6dda113ed68b75b432615fae3b49fb", + "image": ["portainer/portainer-ce:2.9.3"], + "io": {"cumulative_ior": 1187840, "cumulative_iow": 2011136}, + "key": "name", + "memory": {"cache": None, + "limit": 7823585280, + "max_usage": None, + "rss": None, + "usage": 17010688}, + "memory_usage": 17010688, + "name": "portainer", + "network": {"cumulative_rx": 2966333, "cumulative_tx": 0}, + "status": "running", + "uptime": "1 weeks"}]} GET core -------- Get plugin stats:: - # curl http://localhost:61208/api/3/core + # curl http://localhost:61208/api/4/core {"log": 4, "phys": 2} Fields descriptions: @@ -242,7 +345,7 @@ Fields descriptions: Get a specific field:: - # curl http://localhost:61208/api/3/core/phys + # curl http://localhost:61208/api/4/core/phys {"phys": 2} GET cpu @@ -250,29 +353,28 @@ GET cpu Get plugin stats:: - # curl http://localhost:61208/api/3/cpu + # curl http://localhost:61208/api/4/cpu {"cpucore": 4, - "ctx_switches": 0, + "ctx_switches": 1565209189, "guest": 0.0, "guest_nice": 0.0, - "idle": 70.8, - "interrupts": 0, - "iowait": 0.0, + "idle": 69.3, + "interrupts": 673172772, + "iowait": 0.5, "irq": 0.0, "nice": 0.0, - "soft_interrupts": 0, - "softirq": 0.7, + "soft_interrupts": 382231833, + "softirq": 0.0, "steal": 0.0, "syscalls": 0, - "system": 4.4, - "time_since_update": 1, - "total": 29.2, - "user": 24.1} + "system": 3.5, + "total": 30.2, + "user": 26.6} Fields descriptions: * **total**: Sum of all CPU percentages (except idle) (unit is *percent*) -* **system**: percent time spent in kernel space. System CPU time is the time spent running code in the Operating System kernel (unit is *percent*) +* **system**: Percent time spent in kernel space. System CPU time is the time spent running code in the Operating System kernel (unit is *percent*) * **user**: CPU percent time spent in user space. User CPU time is the time spent on the processor running your program's code (or code in libraries) (unit is *percent*) * **iowait**: *(Linux)*: percent time spent by the CPU waiting for I/O operations to complete (unit is *percent*) * **dpc**: *(Windows)*: time spent servicing deferred procedure calls (DPCs) (unit is *percent*) @@ -280,123 +382,167 @@ Fields descriptions: * **irq**: *(Linux and BSD)*: percent time spent servicing/handling hardware/software interrupts. Time servicing interrupts (hardware + software) (unit is *percent*) * **nice**: *(Unix)*: percent time occupied by user level processes with a positive nice value. The time the CPU has spent running users' processes that have been *niced* (unit is *percent*) * **steal**: *(Linux)*: percentage of time a virtual CPU waits for a real CPU while the hypervisor is servicing another virtual processor (unit is *percent*) +* **guest**: *(Linux)*: time spent running a virtual CPU for guest operating systems under the control of the Linux kernel (unit is *percent*) * **ctx_switches**: number of context switches (voluntary + involuntary) per second. A context switch is a procedure that a computer's CPU (central processing unit) follows to change from one task (or process) to another while ensuring that the tasks do not conflict (unit is *number*) +* **ctx_switches_rate_per_sec**: number of context switches (voluntary + involuntary) per second. A context switch is a procedure that a computer's CPU (central processing unit) follows to change from one task (or process) to another while ensuring that the tasks do not conflict per second (unit is *number* per second) +* **ctx_switches_gauge**: number of context switches (voluntary + involuntary) per second. A context switch is a procedure that a computer's CPU (central processing unit) follows to change from one task (or process) to another while ensuring that the tasks do not conflict (cumulative) (unit is *number*) * **interrupts**: number of interrupts per second (unit is *number*) +* **interrupts_rate_per_sec**: number of interrupts per second per second (unit is *number* per second) +* **interrupts_gauge**: number of interrupts per second (cumulative) (unit is *number*) * **soft_interrupts**: number of software interrupts per second. Always set to 0 on Windows and SunOS (unit is *number*) +* **soft_interrupts_rate_per_sec**: number of software interrupts per second. Always set to 0 on Windows and SunOS per second (unit is *number* per second) +* **soft_interrupts_gauge**: number of software interrupts per second. Always set to 0 on Windows and SunOS (cumulative) (unit is *number*) * **syscalls**: number of system calls per second. Always 0 on Linux OS (unit is *number*) +* **syscalls_rate_per_sec**: number of system calls per second. Always 0 on Linux OS per second (unit is *number* per second) +* **syscalls_gauge**: number of system calls per second. Always 0 on Linux OS (cumulative) (unit is *number*) * **cpucore**: Total number of CPU core (unit is *number*) * **time_since_update**: Number of seconds since last update (unit is *seconds*) Get a specific field:: - # curl http://localhost:61208/api/3/cpu/total - {"total": 29.2} + # curl http://localhost:61208/api/4/cpu/total + {"total": 30.2} GET diskio ---------- Get plugin stats:: - # curl http://localhost:61208/api/3/diskio + # curl http://localhost:61208/api/4/diskio [{"disk_name": "sda", "key": "disk_name", - "read_bytes": 0, - "read_count": 0, - "time_since_update": 1, - "write_bytes": 0, - "write_count": 0}, - {"disk_name": "sda1", + "read_bytes": 157324110848, + "read_count": 11374333, + "write_bytes": 201555001344, + "write_count": 6582750}, + {"alias": "InternalDisk", + "disk_name": "sda1", "key": "disk_name", - "read_bytes": 0, - "read_count": 0, - "time_since_update": 1, + "read_bytes": 22958080, + "read_count": 713, "write_bytes": 0, - "write_count": 0}] + "write_count": 78}] + +Fields descriptions: + +* **disk_name**: Disk name (unit is *None*) +* **read_count**: Number of reads (unit is *number*) +* **read_count_rate_per_sec**: Number of reads per second (unit is *number* per second) +* **read_count_gauge**: Number of reads (cumulative) (unit is *number*) +* **write_count**: Number of writes (unit is *number*) +* **write_count_rate_per_sec**: Number of writes per second (unit is *number* per second) +* **write_count_gauge**: Number of writes (cumulative) (unit is *number*) +* **read_bytes**: Number of bytes read (unit is *byte*) +* **read_bytes_rate_per_sec**: Number of bytes read per second (unit is *byte* per second) +* **read_bytes_gauge**: Number of bytes read (cumulative) (unit is *byte*) +* **write_bytes**: Number of bytes written (unit is *byte*) +* **write_bytes_rate_per_sec**: Number of bytes written per second (unit is *byte* per second) +* **write_bytes_gauge**: Number of bytes written (cumulative) (unit is *byte*) Get a specific field:: - # curl http://localhost:61208/api/3/diskio/disk_name + # curl http://localhost:61208/api/4/diskio/disk_name {"disk_name": ["sda", "sda1", "sda2", "sda5", "dm-0", "dm-1"]} Get a specific item when field matches the given value:: - # curl http://localhost:61208/api/3/diskio/disk_name/sda + # curl http://localhost:61208/api/4/diskio/disk_name/sda {"sda": [{"disk_name": "sda", "key": "disk_name", - "read_bytes": 0, - "read_count": 0, - "time_since_update": 1, - "write_bytes": 0, - "write_count": 0}]} + "read_bytes": 157324110848, + "read_count": 11374333, + "write_bytes": 201555001344, + "write_count": 6582750}]} GET fs ------ Get plugin stats:: - # curl http://localhost:61208/api/3/fs - [{"device_name": "/dev/mapper/ubuntu--gnome--vg-root", - "free": 25133506560, + # curl http://localhost:61208/api/4/fs + [{"alias": "Root", + "device_name": "/dev/mapper/ubuntu--gnome--vg-root", + "free": 11921264640, "fs_type": "ext4", "key": "mnt_point", "mnt_point": "/", - "percent": 89.1, + "percent": 94.8, "size": 243334156288, - "used": 205813194752}, + "used": 219025436672}, {"device_name": "zsfpool", - "free": 41811968, + "free": 31195136, "fs_type": "zfs", "key": "mnt_point", "mnt_point": "/zsfpool", - "percent": 0.3, - "size": 41943040, - "used": 131072}] + "percent": 25.4, + "size": 41811968, + "used": 10616832}] + +Fields descriptions: + +* **device_name**: Device name (unit is *None*) +* **fs_type**: File system type (unit is *None*) +* **mnt_point**: Mount point (unit is *None*) +* **size**: Total size (unit is *byte*) +* **used**: Used size (unit is *byte*) +* **free**: Free size (unit is *byte*) +* **percent**: File system usage in percent (unit is *percent*) Get a specific field:: - # curl http://localhost:61208/api/3/fs/mnt_point + # curl http://localhost:61208/api/4/fs/mnt_point {"mnt_point": ["/", "/zsfpool", "/var/snap/firefox/common/host-hunspell"]} Get a specific item when field matches the given value:: - # curl http://localhost:61208/api/3/fs/mnt_point// - {"/": [{"device_name": "/dev/mapper/ubuntu--gnome--vg-root", - "free": 25133506560, + # curl http://localhost:61208/api/4/fs/mnt_point// + {"/": [{"alias": "Root", + "device_name": "/dev/mapper/ubuntu--gnome--vg-root", + "free": 11921264640, "fs_type": "ext4", "key": "mnt_point", "mnt_point": "/", - "percent": 89.1, + "percent": 94.8, "size": 243334156288, - "used": 205813194752}]} + "used": 219025436672}]} GET ip ------ Get plugin stats:: - # curl http://localhost:61208/api/3/ip - {"address": "192.168.1.14", - "gateway": "192.168.1.1", + # curl http://localhost:61208/api/4/ip + {"address": "192.168.0.32", + "gateway": "192.168.0.254", "mask": "255.255.255.0", "mask_cidr": 24, - "public_address": "92.151.148.66", + "public_address": "91.166.228.228", "public_info_human": ""} +Fields descriptions: + +* **address**: Private IP address (unit is *None*) +* **mask**: Private IP mask (unit is *None*) +* **mask_cidr**: Private IP mask in CIDR format (unit is *number*) +* **gateway**: Private IP gateway (unit is *None*) +* **public_address**: Public IP address (unit is *None*) +* **public_info_human**: Public IP information (unit is *None*) + Get a specific field:: - # curl http://localhost:61208/api/3/ip/gateway - {"gateway": "192.168.1.1"} + # curl http://localhost:61208/api/4/ip/gateway + {"gateway": "192.168.0.254"} GET load -------- Get plugin stats:: - # curl http://localhost:61208/api/3/load + # curl http://localhost:61208/api/4/load {"cpucore": 4, - "min1": 1.18505859375, - "min15": 1.17724609375, - "min5": 1.23779296875} + "min1": 1.7509765625, + "min15": 1.4345703125, + "min5": 1.2666015625} Fields descriptions: @@ -407,25 +553,25 @@ Fields descriptions: Get a specific field:: - # curl http://localhost:61208/api/3/load/min1 - {"min1": 1.18505859375} + # curl http://localhost:61208/api/4/load/min1 + {"min1": 1.7509765625} GET mem ------- Get plugin stats:: - # curl http://localhost:61208/api/3/mem - {"active": 3179450368, - "available": 1759965184, - "buffers": 139554816, - "cached": 2369826816, - "free": 1759965184, - "inactive": 3354943488, - "percent": 77.5, - "shared": 580452352, - "total": 7836184576, - "used": 6076219392} + # curl http://localhost:61208/api/4/mem + {"active": 2068942848, + "available": 1466028032, + "buffers": 165359616, + "cached": 1911681024, + "free": 1466028032, + "inactive": 4365434880, + "percent": 81.3, + "shared": 562696192, + "total": 7823585280, + "used": 6357557248} Fields descriptions: @@ -443,22 +589,22 @@ Fields descriptions: Get a specific field:: - # curl http://localhost:61208/api/3/mem/total - {"total": 7836184576} + # curl http://localhost:61208/api/4/mem/total + {"total": 7823585280} GET memswap ----------- Get plugin stats:: - # curl http://localhost:61208/api/3/memswap - {"free": 5171486720, - "percent": 36.0, - "sin": 30833557504, - "sout": 44998725632, + # curl http://localhost:61208/api/4/memswap + {"free": 6025789440, + "percent": 25.4, + "sin": 26750087168, + "sout": 36382937088, "time_since_update": 1, "total": 8082419712, - "used": 2910932992} + "used": 2056630272} Fields descriptions: @@ -472,7 +618,7 @@ Fields descriptions: Get a specific field:: - # curl http://localhost:61208/api/3/memswap/total + # curl http://localhost:61208/api/4/memswap/total {"total": 8082419712} GET network @@ -480,104 +626,107 @@ GET network Get plugin stats:: - # curl http://localhost:61208/api/3/network + # curl http://localhost:61208/api/4/network [{"alias": None, - "cumulative_cx": 1271814348, - "cumulative_rx": 635907174, - "cumulative_tx": 635907174, - "cx": 1070, + "cumulative_cx": 2849154006, + "cumulative_rx": 1424577003, + "cumulative_tx": 1424577003, + "cx": 0, "interface_name": "lo", "is_up": True, "key": "interface_name", - "rx": 535, + "rx": 0, "speed": 0, "time_since_update": 1, - "tx": 535}, - {"alias": None, - "cumulative_cx": 43280474609, - "cumulative_rx": 41602144558, - "cumulative_tx": 1678330051, - "cx": 4727, + "tx": 0}, + {"alias": "WIFI", + "cumulative_cx": 18617767483, + "cumulative_rx": 15193537585, + "cumulative_tx": 3424229898, + "cx": 224, "interface_name": "wlp2s0", "is_up": True, "key": "interface_name", - "rx": 663, + "rx": 98, "speed": 0, "time_since_update": 1, - "tx": 4064}] + "tx": 126}] Fields descriptions: * **interface_name**: Interface name (unit is *string*) * **alias**: Interface alias name (optional) (unit is *string*) -* **rx**: The received/input rate (in bit per second) (unit is *bps*) -* **tx**: The sent/output rate (in bit per second) (unit is *bps*) -* **cx**: The cumulative received+sent rate (in bit per second) (unit is *bps*) -* **cumulative_rx**: The number of bytes received through the interface (cumulative) (unit is *bytes*) -* **cumulative_tx**: The number of bytes sent through the interface (cumulative) (unit is *bytes*) -* **cumulative_cx**: The cumulative number of bytes reveived and sent through the interface (cumulative) (unit is *bytes*) -* **speed**: Maximum interface speed (in bit per second). Can return 0 on some operating-system (unit is *bps*) +* **rx**: The received/input rate (unit is *bitpersecond*) +* **tx**: The sent/output rate (unit is *bitpersecond*) +* **cx**: The cumulative received+sent rate (unit is *bitpersecond*) +* **cumulative_rx**: The number of bytes received through the interface (cumulative) (unit is *byte*) +* **cumulative_tx**: The number of bytes sent through the interface (cumulative) (unit is *byte*) +* **cumulative_cx**: The cumulative number of bytes reveived and sent through the interface (cumulative) (unit is *byte*) +* **speed**: Maximum interface speed (in bit per second). Can return 0 on some operating-system (unit is *bitpersecond*) * **is_up**: Is the interface up ? (unit is *bool*) * **time_since_update**: Number of seconds since last update (unit is *seconds*) Get a specific field:: - # curl http://localhost:61208/api/3/network/interface_name + # curl http://localhost:61208/api/4/network/interface_name {"interface_name": ["lo", "wlp2s0", + "br-40875d2e2716", "docker0", "br_grafana", "mpqemubr0", - "veth0868fe1", - "vboxnet0"]} + "vethbeef843", + "tap-838a195875f", + "lxdbr0", + "veth4cbf8f0a"]} Get a specific item when field matches the given value:: - # curl http://localhost:61208/api/3/network/interface_name/lo + # curl http://localhost:61208/api/4/network/interface_name/lo {"lo": [{"alias": None, - "cumulative_cx": 1271814348, - "cumulative_rx": 635907174, - "cumulative_tx": 635907174, - "cx": 1070, + "cumulative_cx": 2849154006, + "cumulative_rx": 1424577003, + "cumulative_tx": 1424577003, + "cx": 0, "interface_name": "lo", "is_up": True, "key": "interface_name", - "rx": 535, + "rx": 0, "speed": 0, "time_since_update": 1, - "tx": 535}]} + "tx": 0}]} GET now ------- Get plugin stats:: - # curl http://localhost:61208/api/3/now - "2023-07-25 16:02:16 CEST" + # curl http://localhost:61208/api/4/now + "2024-02-03 16:59:21 CET" GET percpu ---------- Get plugin stats:: - # curl http://localhost:61208/api/3/percpu + # curl http://localhost:61208/api/4/percpu [{"cpu_number": 0, "guest": 0.0, "guest_nice": 0.0, - "idle": 30.0, + "idle": 47.0, "iowait": 0.0, "irq": 0.0, "key": "cpu_number", "nice": 0.0, "softirq": 0.0, "steal": 0.0, - "system": 2.0, - "total": 70.0, + "system": 1.0, + "total": 53.0, "user": 4.0}, {"cpu_number": 1, "guest": 0.0, "guest_nice": 0.0, - "idle": 30.0, + "idle": 45.0, "iowait": 0.0, "irq": 0.0, "key": "cpu_number", @@ -585,12 +734,27 @@ Get plugin stats:: "softirq": 0.0, "steal": 0.0, "system": 0.0, - "total": 70.0, - "user": 4.0}] + "total": 55.0, + "user": 7.0}] + +Fields descriptions: + +* **cpu_number**: CPU number (unit is *None*) +* **total**: Sum of CPU percentages (except idle) for current CPU number (unit is *percent*) +* **system**: Percent time spent in kernel space. System CPU time is the time spent running code in the Operating System kernel (unit is *percent*) +* **user**: CPU percent time spent in user space. User CPU time is the time spent on the processor running your program's code (or code in libraries) (unit is *percent*) +* **iowait**: *(Linux)*: percent time spent by the CPU waiting for I/O operations to complete (unit is *percent*) +* **idle**: percent of CPU used by any program. Every program or task that runs on a computer system occupies a certain amount of processing time on the CPU. If the CPU has completed all tasks it is idle (unit is *percent*) +* **irq**: *(Linux and BSD)*: percent time spent servicing/handling hardware/software interrupts. Time servicing interrupts (hardware + software) (unit is *percent*) +* **nice**: *(Unix)*: percent time occupied by user level processes with a positive nice value. The time the CPU has spent running users' processes that have been *niced* (unit is *percent*) +* **steal**: *(Linux)*: percentage of time a virtual CPU waits for a real CPU while the hypervisor is servicing another virtual processor (unit is *percent*) +* **guest**: *(Linux)*: percent of time spent running a virtual CPU for guest operating systems under the control of the Linux kernel (unit is *percent*) +* **guest_nice**: *(Linux)*: percent of time spent running a niced guest (virtual CPU) (unit is *percent*) +* **softirq**: *(Linux)*: percent of time spent handling software interrupts (unit is *percent*) Get a specific field:: - # curl http://localhost:61208/api/3/percpu/cpu_number + # curl http://localhost:61208/api/4/percpu/cpu_number {"cpu_number": [0, 1, 2, 3]} GET ports @@ -598,82 +762,103 @@ GET ports |