diff options
54 files changed, 1867 insertions, 683 deletions
@@ -12,12 +12,17 @@ Under development: https://github.com/nicolargo/glances/issues?q=is%3Aopen+is%3A * The Glances API version 3 is replaced by the version 4. So Restfull API URL is now /api/4/ #2610 * Alias definition change in the configuration file #1735 + Glances version 3.x and lower: + sda1_alias=InternalDisk sdb1_alias=ExternalDisk + Glances version 4.x and higher: + alias=sda1:InternalDisk,sdb1:ExternalDisk - * Alias can now be used to redefine FS name #1735 + + * Alert data model change from a list of list to a list of dict #2633 =============== Version 3.4.0.3 @@ -221,14 +221,16 @@ Run last version of Glances container in *console mode*: docker run --rm -e TZ="${TZ}" -v /var/run/docker.sock:/var/run/docker.sock:ro -v /run/user/1000/podman/podman.sock:/run/user/1000/podman/podman.sock:ro --pid host --network host -it nicolargo/glances:latest-full +By default, the /etc/glances/glances.conf file is used (based on docker-compose/glances.conf). + Additionally, if you want to use your own glances.conf file, you can create your own Dockerfile: .. code-block:: console FROM nicolargo/glances:latest - COPY glances.conf /etc/glances.conf - CMD python -m glances -C /etc/glances.conf $GLANCES_OPT + COPY glances.conf /root/.config/glances/glances.conf + CMD python -m glances -C /root/.config/glances/glances.conf $GLANCES_OPT Alternatively, you can specify something along the same lines with docker run options (notice the `GLANCES_OPT` environment @@ -236,7 +238,7 @@ variable setting parameters for the glances startup command): .. code-block:: console - docker run -e TZ="${TZ}" -v `pwd`/glances.conf:/etc/glances.conf -v /var/run/docker.sock:/var/run/docker.sock:ro -v /run/user/1000/podman/podman.sock:/run/user/1000/podman/podman.sock:ro --pid host -e GLANCES_OPT="-C /etc/glances.conf" -it nicolargo/glances:latest-full + docker run -e TZ="${TZ}" -v `pwd`/glances.conf:/root/.config/glances/glances.conf -v /var/run/docker.sock:/var/run/docker.sock:ro -v /run/user/1000/podman/podman.sock:/run/user/1000/podman/podman.sock:ro --pid host -e GLANCES_OPT="-C /root/.config/glances/glances.conf" -it nicolargo/glances:latest-full Where \`pwd\`/glances.conf is a local directory containing your glances.conf file. diff --git a/conf/glances.conf b/conf/glances.conf index b6687573..4f07a8b0 100644 --- a/conf/glances.conf +++ b/conf/glances.conf @@ -14,14 +14,21 @@ check_update=true history_size=1200 # Set the way Glances should display the date (default is %Y-%m-%d %H:%M:%S %Z) #strftime_format="%Y-%m-%d %H:%M:%S %Z" +# Define external directory for loading additional plugins +# The layout follows the glances standard for plugin definitions +#plugin_dir=/home/user/dev/plugins ############################################################################## # User interface ############################################################################## [outputs] -# Theme name for the Curses interface: black or white +# Theme name (for the moment only for the Curses interface: black or white) curse_theme=black +# Separator in the Curses and WebUI interface (between top and others plugins) +separator=True +# Set the the Curses and WebUI interface left menu plugin list (comma-separated) +#left_menu=network,wifi,connections,ports,diskio,fs,irq,folders,raid,smart,sensors,now # Limit the number of processes to display (for the WebUI) max_processes_display=25 # Set the URL prefix (for the WebUI and the API) diff --git a/docker-compose/glances.conf b/docker-compose/glances.conf index f40eade9..e3924ee3 100644 --- a/docker-compose/glances.conf +++ b/docker-compose/glances.conf @@ -22,6 +22,10 @@ history_size=1200 [outputs] # Theme name for the Curses interface: black or white curse_theme=black +# Separator in the Curses and WebUI interface (between top and others plugins) +separator=True +# Set the the Curses and WebUI interface left menu plugin list (comma-separated) +#left_menu=network,wifi,connections,ports,diskio,fs,irq,folders,raid,smart,sensors,now # Limit the number of processes to display (for the WebUI) max_processes_display=25 # Set the URL prefix (for the WebUI and the API) @@ -93,6 +97,7 @@ steal_warning=70 steal_critical=90 #steal_log=True # + # Context switch limit (core / second) # Leave commented to just use the default config (critical is 50000*# (Logical CPU cores) #ctx_switches_careful=10000 diff --git a/docker-files/alpine.Dockerfile b/docker-files/alpine.Dockerfile index f1eb2455..a7624b4b 100644 --- a/docker-files/alpine.Dockerfile +++ b/docker-files/alpine.Dockerfile @@ -4,11 +4,13 @@ # https://github.com/nicolargo/glances # -# WARNING: the versions should be set. -# Ex: Python 3.11 for Alpine 3.18 # Note: ENV is for future running containers. ARG for building your Docker image. -ARG IMAGE_VERSION=3.18.4 +# WARNING: the Alpine image version and Python version should be set. +# Alpine 3.18 tag is a link to the latest 3.18.x version. +# Be aware that if you change the Alpine version, you may have to change the Python version. + +ARG IMAGE_VERSION=3.19 ARG PYTHON_VERSION=3.11 ############################################################################## @@ -83,7 +85,7 @@ RUN python${PYTHON_VERSION} -m pip install --target="/venv/lib/python${PYTHON_VE FROM base as release # Copy source code and config file -COPY ./docker-compose/glances.conf /etc/glances.conf +COPY ./docker-compose/glances.conf /etc/glances/glances.conf COPY /glances /app/glances # Copy binary and update PATH diff --git a/docker-files/ubuntu.Dockerfile b/docker-files/ubuntu.Dockerfile index f4ef7c29..be5bc09d 100644 --- a/docker-files/ubuntu.Dockerfile +++ b/docker-files/ubuntu.Dockerfile @@ -77,7 +77,7 @@ RUN python${PYTHON_VERSION} -m pip install --target="/venv/lib/python${PYTHON_VE FROM base as release # Copy Glances source code and config file -COPY ./docker-compose/glances.conf /etc/glances.conf +COPY ./docker-compose/glances.conf /etc/glances/glances.conf COPY /glances /app/glances # Copy binary and update PATH diff --git a/docs/api.rst b/docs/api.rst index 708a105c..62509320 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,12 +3,22 @@ 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 ------- @@ -30,10 +40,11 @@ For example: 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 ------------------ +API documentation URL +--------------------- -The API documentation is available at the following URL: ``http://localhost:61208/docs#/``. +The API documentation is embeded in the server and available at the following URL: +``http://localhost:61208/docs#/``. WebUI refresh ------------- @@ -98,18 +109,54 @@ GET alert Get plugin stats:: # curl http://localhost:61208/api/4/alert - [[1702733581.0, - -1, - "WARNING", - "MEM", - 80.72395821062744, - 80.72395821062744, - 80.72395821062744, - 80.72395821062744, - 1, - [], - "", - "memory_percent"]] + [{"avg": 75.58190732727591, + "begin": 1705242982.0, + "count": 1, + "desc": "", + "end": -1, + "max": 75.58190732727591, + "min": 75.58190732727591, + "sort": "memory_percent", + "state": "WARNING", + "sum": 75.58190732727591, + "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": [1705242982.0]} + +Get a specific item when field matches the given value:: + + # curl http://localhost:61208/api/4/alert/begin/1705242982.0 + {"1705242982.0": [{"avg": 75.58190732727591, + "begin": 1705242982.0, + "count": 1, + "desc": "", + "end": -1, + "max": 75.58190732727591, + "min": 75.58190732727591, + "sort": "memory_percent", + "state": "WARNING", + "sum": 75.58190732727591, + "top": [], + "type": "MEM"}]} GET amps -------- @@ -125,7 +172,7 @@ Get plugin stats:: "refresh": 3.0, "regex": True, "result": None, - "timer": 0.30402588844299316}, + "timer": 0.19934892654418945}, {"count": 0, "countmax": 20.0, "countmin": None, @@ -134,7 +181,17 @@ Get plugin stats:: "refresh": 3.0, "regex": True, "result": None, - "timer": 0.3038666248321533}] + "timer": 0.19925165176391602}] + +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:: @@ -152,7 +209,7 @@ Get a specific item when field matches the given value:: "refresh": 3.0, "regex": True, "result": None, - "timer": 0.30402588844299316}]} + "timer": 0.19934892654418945}]} GET connections --------------- @@ -162,6 +219,18 @@ Get plugin stats:: # 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/4/connections/net_connections_enabled @@ -173,73 +242,97 @@ GET containers Get plugin stats:: # 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": "1 weeks", - "cpu": {"total": 6.604897042562196e-07}, - "cpu_percent": 6.604897042562196e-07, + [{"command": "top", + "cpu": {"total": 1.8635523677666806e-06}, + "cpu_percent": 1.8635523677666806e-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": 1306624.0}, + "memory_usage": 1306624.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"}, + {"command": "", + "cpu": {"total": 3.4505346487574547e-10}, + "cpu_percent": 3.4505346487574547e-10, + "created": "2022-10-22T14:23:03.120912374+02:00", + "engine": "podman", + "id": "9491515251edcd5bb5dc17205d7ee573c0be96fe0b08b0a12a7e2cea874565ea", + "image": "k8s.gcr.io/pause:3.5", + "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": 290816.0}, + "memory_usage": 290816.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", + "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": ["sad_darwin", "8d0f1c783def-infra", "portainer"]} + +Get a specific item when field matches the given value:: + + # curl http://localhost:61208/api/4/containers/name/sad_darwin + {"sad_darwin": [{"command": "top", + "cpu": {"total": 1.8635523677666806e-06}, + "cpu_percent": 1.8635523677666806e-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_r": 0.0, - "io_w": 0.0, + "io_rx": 0.0, + "io_wx": 0.0, "key": "name", - "memory": {"limit": 7823585280.0, "usage": 1441792.0}, - "memory_usage": 1441792.0, + "memory": {"limit": 7823585280.0, "usage": 1306624.0}, + "memory_usage": 1306624.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"}, - {"Command": [], - "Created": "2022-10-22T14:23:03.120912374+02:00", - "Id": "9491515251edcd5bb5dc17205d7ee573c0be96fe0b08b0a12a7e2cea874565ea", - "Image": "["k8s.gcr.io/pause:3.5"]", - "Status": "running", - "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": 368640.0}, - "memory_usage": 368640.0, |