diff options
| author | nicolargo <nicolas@nicolargo.com> | 2023-12-16 14:50:57 +0100 |
|---|---|---|
| committer | nicolargo <nicolas@nicolargo.com> | 2023-12-16 14:50:57 +0100 |
| commit | 32b33b588380df490d0399aaf653200b26d83386 (patch) | |
| tree | 14aa08103d47f7301441e92a64bdf011272fd64c | |
| parent | 3d7b32483924a8168cae86044c5db5f9b88fa359 (diff) | |
| parent | c976f94b1339c9ea718e11dbe512d3e0214ccff2 (diff) | |
Merge branch 'issue2181' into develop
41 files changed, 1437 insertions, 1130 deletions
@@ -80,6 +80,9 @@ test-min: ## Run unit tests in minimal environment test-min-with-upgrade: venv-min-upgrade ## Upgrade deps and run unit tests in minimal environment ./venv-min/bin/python ./unitest.py +test-restful-api: ## Run unit tests of the RESTful API + ./venv/bin/python ./unitest-restful.py + # =================================================================== # Linters, profilers and cyber security # =================================================================== @@ -92,17 +92,19 @@ Optional dependencies: - ``batinfo`` (for battery monitoring) - ``bernhard`` (for the Riemann export module) -- ``bottle`` (for Web server mode) - ``cassandra-driver`` (for the Cassandra export module) - ``chevron`` (for the action script feature) - ``docker`` (for the Containers Docker monitoring support) - ``elasticsearch`` (for the Elastic Search export module) +- ``FastAPI`` and ``Uvicorn`` (for Web server mode) - ``graphitesender`` (For the Graphite export module) - ``hddtemp`` (for HDD temperature monitoring support) [Linux-only] - ``influxdb`` (for the InfluxDB version 1 export module) - ``influxdb-client`` (for the InfluxDB version 2 export module) +- ``jinja2`` (for templating, used under the hood by FastAPI) - ``kafka-python`` (for the Kafka export module) - ``netifaces`` (for the IP plugin) +- ``orjson`` (fast JSON library, used under the hood by FastAPI) - ``py3nvml`` (for the GPU plugin) - ``pycouchdb`` (for the CouchDB export module) - ``pika`` (for the RabbitMQ/ActiveMQ export module) @@ -207,10 +209,10 @@ Get the Glances container: The following tags are availables: - *latest-full* for a full Alpine Glances image (latest release) with all dependencies -- *latest* for a basic Alpine Glances (latest release) version with minimal dependencies (Bottle and Docker) +- *latest* for a basic Alpine Glances (latest release) version with minimal dependencies (FastAPI and Docker) - *dev* for a basic Alpine Glances image (based on development branch) with all dependencies (Warning: may be instable) - *ubuntu-latest-full* for a full Ubuntu Glances image (latest release) with all dependencies -- *ubuntu-latest* for a basic Ubuntu Glances (latest release) version with minimal dependencies (Bottle and Docker) +- *ubuntu-latest* for a basic Ubuntu Glances (latest release) version with minimal dependencies (FastAPI and Docker) - *ubuntu-dev* for a basic Ubuntu Glances image (based on development branch) with all dependencies (Warning: may be instable) Run last version of Glances container in *console mode*: @@ -319,7 +321,7 @@ Start Termux on your device and enter: $ apt update $ apt upgrade $ apt install clang python - $ pip install bottle + $ pip install fastapi uvicorn orjson jinja2 $ pip install glances And start Glances: diff --git a/conf/glances.conf b/conf/glances.conf index 2ab073e2..a5d72a12 100644 --- a/conf/glances.conf +++ b/conf/glances.conf @@ -23,7 +23,7 @@ history_size=1200 # Theme name for the Curses interface: black or white curse_theme=black # Limit the number of processes to display (for the WebUI) -max_processes_display=30 +max_processes_display=25 # Set the URL prefix (for the WebUI and the API) # Example: url_prefix=/glances/ => http://localhost/glances/ # The final / is mandatory diff --git a/docker-compose/glances.conf b/docker-compose/glances.conf index 9f91be17..f40eade9 100644 --- a/docker-compose/glances.conf +++ b/docker-compose/glances.conf @@ -23,7 +23,7 @@ history_size=1200 # Theme name for the Curses interface: black or white curse_theme=black # Limit the number of processes to display (for the WebUI) -max_processes_display=30 +max_processes_display=25 # Set the URL prefix (for the WebUI and the API) # Example: url_prefix=/glances/ => http://localhost/glances/ # The final / is mandatory diff --git a/docs/api.rst b/docs/api.rst index 2889f469..708a105c 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -12,12 +12,14 @@ The Glances Restfull/API server could be ran using the following command line: 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 +27,30 @@ 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 +----------------- + +The API documentation is 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 +58,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 +89,7 @@ Get the plugins list:: "smart", "system", "uptime", + "version", "wifi"] GET alert @@ -83,15 +97,15 @@ GET alert Get plugin stats:: - # curl http://localhost:61208/api/3/alert - [[1702235377.0, + # curl http://localhost:61208/api/4/alert + [[1702733581.0, -1, "WARNING", "MEM", - 80.7320208056836, - 80.7320208056836, - 80.7320208056836, - 80.7320208056836, + 80.72395821062744, + 80.72395821062744, + 80.72395821062744, + 80.72395821062744, 1, [], "", @@ -102,7 +116,7 @@ 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 +125,7 @@ Get plugin stats:: "refresh": 3.0, "regex": True, "result": None, - "timer": 0.39360761642456055}, + "timer": 0.30402588844299316}, {"count": 0, "countmax": 20.0, "countmin": None, @@ -120,16 +134,16 @@ Get plugin stats:: "refresh": 3.0, "regex": True, "result": None, - "timer": 0.39345741271972656}] + "timer": 0.3038666248321533}] 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 +152,19 @@ Get a specific item when field matches the given value:: "refresh": 3.0, "regex": True, "result": None, - "timer": 0.39360761642456055}]} + "timer": 0.30402588844299316}]} 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} 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,22 +172,45 @@ GET containers Get plugin stats:: - # curl http://localhost:61208/api/3/containers - {"containers": [{"Command": ["top"], + # curl http://localhost:61208/api/4/containers + {"containers": [{"Command": ["/portainer"], + "Created": "2022-10-29T14:59:10.266701439Z", + "Id": "3abd51c615968482d9ccff5afc629f267f6dda113ed68b75b432615fae3b49fb", + "Image": ["portainer/portainer-ce:2.9.3"], + "Status": "running", + "Uptime": "3 weeks", + "cpu": {"total": 0.0}, + "cpu_percent": 0.0, + "engine": "docker", + "io": {"cumulative_ior": 1904640, "cumulative_iow": 2256896}, + "io_r": None, + "io_w": None, + "key": "name", + "memory": {"cache": None, + "limit": 7823585280, + "max_usage": None, + "rss": None, + "usage": 13836288}, + "memory_usage": 13836288, + "name": "portainer", + "network": {"cumulative_rx": 7106388, "cumulative_tx": 0}, + "network_rx": None, + "network_tx": None}, + {"Command": ["top"], "Created": "2023-12-09T10:45:34.339489876+01:00", "Id": "481d6ffb7eef284d062628cf350bdd9ce0a803db8a2a505d75565ed24322b714", "Image": "["docker.io/library/ubuntu:latest"]", "Status": "running", - "Uptime": "yesterday", - "cpu": {"total": 2.756671645021486e-07}, - "cpu_percent": 2.756671645021486e-07, + "Uptime": "1 weeks", + "cpu": {"total": 6.604897042562196e-07}, + "cpu_percent": 6.604897042562196e-07, "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": 7823585280.0, "usage": 1974272.0}, - "memory_usage": 1974272.0, + "memory": {"limit": 7823585280.0, "usage": 1441792.0}, + "memory_usage": 1441792.0, "name": "sad_darwin", "network": {"rx": 0.0, "time_since_update": 1, "tx": 0.0}, "network_rx": 0.0, @@ -185,41 +222,22 @@ Get plugin stats:: "Id": "9491515251edcd5bb5dc17205d7ee573c0be96fe0b08b0a12a7e2cea874565ea", "Image": "["k8s.gcr.io/pause:3.5"]", "Status": "running", - "Uptime": "yesterday", - "cpu": {"total": 3.1294144561318065e-10}, - "cpu_percent": 3.1294144561318065e-10, + "Uptime": "1 weeks", + "cpu": {"total": 3.231862023627245e-10}, + "cpu_percent": 3.231862023627245e-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": 7823585280.0, "usage": 692224.0}, - "memory_usage": 692224.0, + "memory": {"limit": 7823585280.0, "usage": 368640.0}, + "memory_usage": 368640.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"}, - {"Command": ["/portainer"], - "Created": "2022-10-29T14:59:10.266701439Z", - "Id": "3abd51c615968482d9ccff5afc629f267f6dda113ed68b75b432615fae3b49fb", - "Image": ["portainer/portainer-ce:2.9.3"], - "Status": "running", - "Uptime": "2 weeks", - "cpu": {"total": 0.0}, - "cpu_percent": 0.0, - "engine": "docker", - "io": {}, - "io_r": None, - "io_w": None, - "key": "name", - "memory": {}, - "memory_usage": None, - "name": "portainer", - "network": {}, - "network_rx": None, - "network_tx": None}], + "pod_name": "8d0f1c783def-infra"}], "version": {}, "version_podman": {}} @@ -228,7 +246,7 @@ 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: @@ -238,7 +256,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 @@ -246,24 +264,24 @@ GET cpu Get plugin stats:: - # curl http://localhost:61208/api/3/cpu + # curl http://localhost:61208/api/4/cpu {"cpucore": 4, "ctx_switches": 0, "guest": 0.0, "guest_nice": 0.0, - "idle": 55.5, + "idle": 73.7, "interrupts": 0, - "iowait": 1.2, + "iowait": 0.2, "irq": 0.0, "nice": 0.0, "soft_interrupts": 0, - "softirq": 0.4, + "softirq": 0.0, "steal": 0.0, "syscalls": 0, - "system": 6.5, + "system": 2.0, "time_since_update": 1, - "total": 43.0, - "user": 36.3} + "total": 26.2, + "user": 24.2} Fields descriptions: @@ -285,15 +303,15 @@ Fields descriptions: Get a specific field:: - # curl http://localhost:61208/api/3/cpu/total - {"total": 43.0} + # curl http://localhost:61208/api/4/cpu/total + {"total": 26.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, @@ -311,12 +329,12 @@ Get plugin stats:: 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, @@ -330,69 +348,66 @@ GET fs Get plugin stats:: - # curl http://localhost:61208/api/3/fs + # curl http://localhost:61208/api/4/fs [{"device_name": "/dev/mapper/ubuntu--gnome--vg-root", - "free": 24783605760, + "free": 26169372672, "fs_type": "ext4", "key": "mnt_point", "mnt_point": "/", - "percent": 89.3, + "percent": 88.7, "size": 243334156288, - "used": 206163095552}, + "used": 204777328640}, {"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}] 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// + # curl http://localhost:61208/api/4/fs/mnt_point// {"/": [{"device_name": "/dev/mapper/ubuntu--gnome--vg-root", - "free": 24783605760, + "free": 26169372672, "fs_type": "ext4", "key": "mnt_point", "mnt_point": "/", - "percent": 89.3, + "percent": 88.7, "size": 243334156288, - "used": 206163095552}]} + "used": 204777328640}]} GET ip ------ Get plugin stats:: - # curl http://localhost:61208/api/3/ip - {"address": "192.168.0.32", - "gateway": "192.168.0.254", + # curl http://localhost:61208/api/4/ip + {"address": "192.168.1.14", + "gateway": "192.168.1.1", "mask": "255.255.255.0", "mask_cidr": 24, - "public_address": "91.166.228.228", + "public_address": "92.151.148.66", "public_info_human": ""} Get a specific field:: - # curl http://localhost:61208/api/3/ip/gateway - {"gateway": "192.168.0.254"} + # curl http://localhost:61208/api/4/ip/gateway + {"gateway": "192.168.1.1"} GET load -------- Get plugin stats:: - # curl http://localhost:61208/api/3/load - {"cpucore": 4, - "min1": 1.86572265625, - "min15": 1.49169921875, - "min5": 1.7294921875} + # curl http://localhost:61208/api/4/load + {"cpucore": 4, "min1": 1.3134765625, "min15": 1.35009765625, "min5": 1.5234375} Fields descriptions: @@ -403,25 +418,25 @@ Fields descriptions: Get a specific field:: - # curl http://localhost:61208/api/3/load/min1 - {"min1": 1.86572265625} + # curl http://localhost:61208/api/4/load/min1 + {"min1": 1.3134765625} GET mem ------- Get plugin stats:: - # curl http://localhost:61208/api/3/mem - {"active": 2548203520, - "available": 1507446784, - "buffers": 83345408, - "cached": 1794064384, - "free": 1507446784, - "inactive": 3827736576, + # curl http://localhost:61208/api/4/mem + {"active": 3005665280, + "available": 1508077568, + "buffers": 124248064, + "cached": 1833496576, + "free": 1508077568, + "inactive": 3188097024, "percent": 80.7, - "shared": 454299648, + "shared": 559996928, "total": 7823585280, - "used": 6316138496} + "used": 6315507712} Fields descriptions: @@ -439,7 +454,7 @@ Fields descriptions: Get a specific field:: - # curl http://localhost:61208/api/3/mem/total + # curl http://localhost:61208/api/4/mem/total {"total": 7823585280} GET memswap @@ -447,14 +462,14 @@ GET memswap Get plugin stats:: - # curl http://localhost:61208/api/3/memswap - {"free": 5210046464, - "percent": 35.5, - "sin": 2560524288, - "sout": 5443428352, + # curl http://localhost:61208/api/4/memswap + {"free": 4914995200, + "percent": 39.2, + "sin": 6458191872, + "sout": 11348365312, "time_since_update": 1, "total": 8082419712, - "used": 2872373248} + "used": 3167424512} Fields descriptions: @@ -468,7 +483,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 @@ -476,23 +491,23 @@ GET network Get plugin stats:: - # curl http://localhost:61208/api/3/network + # curl http://localhost:61208/api/4/network [{"alias": None, - "cumulative_cx": 355930708, - "cumulative_rx": 177965354, - "cumulative_tx": 177965354, - "cx": 16048, + "cumulative_cx": 1492376856, + "cumulative_rx": 746188428, + "cumulative_tx": 746188428, + "cx": 0, "interface_name": "lo", "is_up": True, "key": "interface_name", - "rx": 8024, + "rx": 0, "speed": 0, "time_since_update": 1, - "tx": 8024}, + "tx": 0}, {"alias": None, - "cumulative_cx": 4299682624, - "cumulative_rx": 4046511475, - "cumulative_tx": 253171149, + "cumulative_cx": 5862371250, + "cumulative_rx": 5524324325, + "cumulative_tx": 338046925, "cx": 224, "interface_name": "wlp2s0", "is_up": True, @@ -518,7 +533,7 @@ Fields descriptions: 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", @@ -529,64 +544,64 @@ Get a specific field:: 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 |