# linux2mqtt
> DISCLAIMER: See credits at the bottom to learn more about the original code for this project.
[](https://github.com/miaucl/linux2mqtt/actions/workflows/mypy.yaml)
[](https://github.com/miaucl/linux2mqtt/actions/workflows/ruff.yml)
[](https://github.com/miaucl/linux2mqtt/actions/workflows/markdownlint.yml)
[](https://github.com/miaucl/linux2mqtt/actions/workflows/publish.yml)
Publish linux system performance metrics to a MQTT broker. It will also publish Home Assistant MQTT Discovery messages so that (binary) sensors automatically show up in Home Assistant.
_This is part of a family of similar tools:_
* [miaucl/linux2mqtt](https://github.com/miaucl/linux2mqtt)
* [miaucl/docker2mqtt](https://github.com/miaucl/docker2mqtt)
* [miaucl/systemctl2mqtt](https://github.com/miaucl/systemctl2mqtt)
It is available as python package on [pypi/linux2mqtt](https://pypi.org/p/linux2mqtt).
[](https://pypi.org/p/linux2mqtt)
`linux2mqtt` is a lightweight wrapper around [psutil](https://pypi.org/project/psutil/) that publishes CPU utilization, free memory, and other system-level stats to a MQTT broker. The primary use case is to collect system performance metrics for ingestion into [Home Assistant](https://www.home-assistant.io/) (HA) for alerting, reporting, and firing off any number of automations. However, given the minimal nature of this code, it could be used for other purposes as well.
## Installation and Deployment
It is available as python package on [pypi/systemctl2mqtt](https://pypi.org/p/systemctl2mqtt).
### Pypi package
[](https://pypi.org/p/systemctl2mqtt)
```bash
pip install linux2mqtt
linux2mqtt --name MyServerName --cpu=60 --vm -vvvvv
```
Usage
```python
from linux2mqtt import Linux2Mqtt, DEFAULT_CONFIG
cfg = Linux2MqttConfig({
**DEFAULT_CONFIG,
"host": "mosquitto",
})
try:
linux2mqtt = Linux2Mqtt(cfg)
linux2mqtt.connect()
linux2mqtt.loop_busy()
except Exception as ex:
# Do something
```
This will install the latest release of `linux2mqtt`, create the necessary MQTT topics, and start sending virtual memory and CPU utilization metrics. The MQTT broker is assumed to be running on `localhost`. If your broker is running on a different host, specify the hostname or IP address using the `--host` parameter.
`linux2mqtt`requires Python 3.11 or above. If your default Python version is older, you may have to explicitly specify the `pip` version by using `pip3` or `pip-3`.
* The `--name` parameter is used for the friendly name of the sensor in Home Assistant and for the MQTT topic names. If not specified, it defaults to the hostname of the machine.
* Instantaneous CPU utilization isn't all that informative. It's normal for a CPU to occasionally spike to 100% for a few moments and means that the chip is being utilized to its full potential. However, if the CPU stays pegged at/near 100% over a longer period of time, it is indicative of a bottleneck. The `--cpu=60` parameter is the collection interval for the CPU metrics. Here CPU metrics are gathered for 60 seconds and then the average value is published to MQTT state topic for the sensor. A good value for this option is anywhere between 60 and 1800 seconds (1 to 15 minutes), depending on typical workloads.
* The `--vm` flag indicates that virtual memory (RAM) metrics should also be published.
* `-vvvvv` (five v's) specifies debug-level logging to the console. Reduce the quantity of v's to reduce the logging verbosity.
By default, `linux2mqtt` will publish system metrics every 30 seconds. This can be changed using the `--interval` option.
## Additional Metrics
### Disk Usage
`linux2mqtt` can publish disk usage metrics using the `du` option. Multiple `du` options can be specified to monitor different volumes. Each volume will present as a separate sensor in Home Assistant. The sensor state reports the percentage of total volume space consumed. Additional data (total volume size in bytes, free bytes, and used bytes) are accessible as state attributes on each sensor.
`linux2mqtt --name Server1 -vvvvv --cpu=60 --vm --du='/var/spool' --du='/'`
### Network Throughput
Network throughput (amount of traffic) metrics are also available. Using one or more `--net` parameters, specify the interface name and the collection interval (as discussed in the CPU metrics documentation), separated by a comma. A separate MQTT topic is created for each interface and each will appear as a separate sensor in HA.
The sensor state equals average throughput of the interface during the collection interval (combining both transmit and receive) in kilobits per second. More detail is available in the state attributes, such as: individual TX and RX rates, number of packets, total bytes sent and received, etc. Except for TX and RX rates, all attribute values are total accumulated values since the interface was reset. Thus, expect to see very large numbers if the interface has been online a while.
`linux2mqtt --name Server1 -vvvvv --interval 60 --net=eth0,15`
This will publish network throughput information about Server1's `eth0` interface to the MQTT broker once every 60 seconds. The sensor state will equal the average network throughput over the previous 15 seconds.
### Thermal zones
`linux2mqtt` can publish temperature metrics for thermal zones using the `temp` option. Each thermal zone will present as a separate sensor in Home Assistant. The sensor state reports the temperature in `°C`. Additional data is accessible as state attributes on each sensor.
`linux2mqtt --name Server1 -vvvvv --cpu=60 --vm --temp`
### Fan speeds
`linux2mqtt` can publish fan speeds using the `fan` option. Each fan will present as a separate sensor in Home Assistant, but be aware this is only for monitoring which means it is not an actual fan entity but only presents itself as a sensor with **no** device class and **no** unit of measurements. The sensor state reports the fan speed in `RPM`. Additional data is accessible as state attributes on each sensor.
`linux2mqtt --name Server1 -vvvvv --cpu=60 --vm --fan`
## Compatibility
`linux2mqtt` has been tested to work on CentOS, Ubuntu, and Debian (Raspberry Pi), even tough some features are not available everywhere. **Python 3.10 (or above) is recommended.**
## Running in the Background (Daemonizing)
`linux2mqtt` runs as a foreground task at the command prompt. In order to run in the program in the background, or automatically at boot, the process has to be daemonized. The easiest way to do this is on a UNIX-like OS (Linux/BSD) is with [Supervisor](http://supervisord.org/) or [systemd](https://systemd.io). Example Supervisor and service configuration file for `linux2mqtt` is included in the [/contrib/](https://github.com/miaucl/linux2mqtt/blob/master/contrib/) directory.
## Using with Home Assistant (HA)
Once `linux2mqtt` is collecting data and publishing it to MQTT, it's rather trivial to use the data in Home Assistant.
A few assumptions:
* **Home Assistant is already configured to use a MQTT broker.** Setting up MQTT and HA is beyond the scope of this documentation. However, there are a lot of great tutorials on YouTube. An external broker (or as add-on) like [Mosquitto](https://mosquitto.org/) will need to be installed and the HA MQTT integration configured.
* **The HA MQTT integration is configured to use `homeassistant` as the MQTT autodiscovery prefix.** This is the default for the integration and also the default for `linux2mqtt`. If you have changed this from the default, use the `--homeassistant-prefix` parameter to specify the correct one.
* **You're not using TLS to connect to the MQTT broker.** Currently `linux2mqtt` only works with unencrypted connections. Username / password authentication can be specified with the `--username` and `--password` parameters, but TLS encryption is not yet supported.
Using the default prefix and a system name of `NUC` (the name of the server), the following state can be found in the "States" section of Developer Tools in HA:
### Lovelace Dashboards
To visualize, use the excellent [mini-graph-card](https://github.com/kalkih/mini-graph-card) custom card for Lovelace dashboards. It's highly-customizable and fairly easy to make great looking charts in HA. Here is a very basic config example of using the metrics produced by `linux2mqtt` to display the past 12 hours of CPU and memory utilization on an Intel NUC server:
```yaml
entities:
- entity: sensor.nuc_cpu
name: CPU Utilization
show_legend: true
show_line: true
show_points: false
- entity: sensor.nuc_virtual_memory
name: Memory Utilization
show_legend: true
show_line: true
show_points: false
hours_to_show: 12
line_width: 2
lower_bound: 0
name: NUC System Metrics
points_per_hour: 6
show:
labels: false
labels_secondary: false
type: 'custom:mini-graph-card'
upper_bound: 100
```
## Documentation
Using `mkdocs`, the documentation and reference is generated and available on [github pages](https://miaucl.github.io/linux2mqtt/).
## Dev
Setup the dev environment using VSCode, it is highly recommended.
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements_dev.txt
```
Install [pre-commit](https://pre-commit.com)
```bash
pre-commit install
# Run the commit hooks manually
pre-commit run --all-files
```
Following VSCode integrations may be helpful:
* [ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)
* [mypy](https://marketplace.visualstudio.com/items?itemName=matangover.mypy)
* [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
### Releasing
It is only possible to release a _final version_ on the `master` branch. For it to pass the gates of the `publish` workflow, it must have the same version in the `tag`, the `setup.cfg`, the `bring_api/__init__.py` and an entry in the `CHANGELOG.md` file.
To release a prerelease version, no changelog entry is required, but it can only happen on a feature branch (**not** `master` branch). Also, prerelease versions are marked as such in the github release page.
## Credits
This is a detached fork from the repo <https://github.com/jamiebegin/linux2mqtt>, which does not seem to get evolved anymore.
> This project is intended to be an alternative to the (very good) [Glances](https://github.com/nicolargo/glances) project. The primary design difference is that the Glances integration into Home Assistant relies on periodically polling a RESTful API. However, the pub/sub model of [MQTT](http://mqtt.org/)--which is already widely used in the home automation community--is an ideal fit for real-time reporting of this type of data. Additionally `linux2mqtt` can be very lightweight because it omits the GUI and alerting elements of Glances (which are redundant when used in conjunction with HA).
# CHANGELOG
## 1.2.0
* Update version package identifier and bump setuptools
* Bump psutil to 6
* Fix mypy config
## 1.1.0
* Add temperature of thermal zones to metrics
* Add fan speed of cooling devices to metrics
* Update the discovery jsons for home assistant
## 1.0.0
* Initial version.
Raw data
{
"_id": null,
"home_page": "https://github.com/miaucl/linux2mqtt",
"name": "linux2mqtt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mqtt, psutil, metrics, linux",
"author": "Cyrill Raccaud",
"author_email": "cyrill.raccaud+pypi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/58/2d/c3f9d25f9255fea8f20ba44a07d58c3076e5d067756b9251acfeb511487b/linux2mqtt-1.2.0.tar.gz",
"platform": null,
"description": "# linux2mqtt\n\n> DISCLAIMER: See credits at the bottom to learn more about the original code for this project.\n\n[](https://github.com/miaucl/linux2mqtt/actions/workflows/mypy.yaml)\n[](https://github.com/miaucl/linux2mqtt/actions/workflows/ruff.yml)\n[](https://github.com/miaucl/linux2mqtt/actions/workflows/markdownlint.yml)\n[](https://github.com/miaucl/linux2mqtt/actions/workflows/publish.yml)\n\nPublish linux system performance metrics to a MQTT broker. It will also publish Home Assistant MQTT Discovery messages so that (binary) sensors automatically show up in Home Assistant.\n\n_This is part of a family of similar tools:_\n\n* [miaucl/linux2mqtt](https://github.com/miaucl/linux2mqtt)\n* [miaucl/docker2mqtt](https://github.com/miaucl/docker2mqtt)\n* [miaucl/systemctl2mqtt](https://github.com/miaucl/systemctl2mqtt)\n\nIt is available as python package on [pypi/linux2mqtt](https://pypi.org/p/linux2mqtt).\n[](https://pypi.org/p/linux2mqtt)\n\n`linux2mqtt` is a lightweight wrapper around [psutil](https://pypi.org/project/psutil/) that publishes CPU utilization, free memory, and other system-level stats to a MQTT broker. The primary use case is to collect system performance metrics for ingestion into [Home Assistant](https://www.home-assistant.io/) (HA) for alerting, reporting, and firing off any number of automations. However, given the minimal nature of this code, it could be used for other purposes as well.\n\n## Installation and Deployment\n\nIt is available as python package on [pypi/systemctl2mqtt](https://pypi.org/p/systemctl2mqtt).\n\n### Pypi package\n\n[](https://pypi.org/p/systemctl2mqtt)\n\n```bash\npip install linux2mqtt \nlinux2mqtt --name MyServerName --cpu=60 --vm -vvvvv\n```\n\nUsage\n\n```python\nfrom linux2mqtt import Linux2Mqtt, DEFAULT_CONFIG\n\ncfg = Linux2MqttConfig({ \n **DEFAULT_CONFIG,\n \"host\": \"mosquitto\",\n})\n\ntry:\n linux2mqtt = Linux2Mqtt(cfg)\n linux2mqtt.connect()\n linux2mqtt.loop_busy()\n\nexcept Exception as ex:\n # Do something\n```\n\nThis will install the latest release of `linux2mqtt`, create the necessary MQTT topics, and start sending virtual memory and CPU utilization metrics. The MQTT broker is assumed to be running on `localhost`. If your broker is running on a different host, specify the hostname or IP address using the `--host` parameter.\n\n`linux2mqtt`requires Python 3.11 or above. If your default Python version is older, you may have to explicitly specify the `pip` version by using `pip3` or `pip-3`.\n\n* The `--name` parameter is used for the friendly name of the sensor in Home Assistant and for the MQTT topic names. If not specified, it defaults to the hostname of the machine.\n* Instantaneous CPU utilization isn't all that informative. It's normal for a CPU to occasionally spike to 100% for a few moments and means that the chip is being utilized to its full potential. However, if the CPU stays pegged at/near 100% over a longer period of time, it is indicative of a bottleneck. The `--cpu=60` parameter is the collection interval for the CPU metrics. Here CPU metrics are gathered for 60 seconds and then the average value is published to MQTT state topic for the sensor. A good value for this option is anywhere between 60 and 1800 seconds (1 to 15 minutes), depending on typical workloads.\n* The `--vm` flag indicates that virtual memory (RAM) metrics should also be published.\n* `-vvvvv` (five v's) specifies debug-level logging to the console. Reduce the quantity of v's to reduce the logging verbosity.\n\nBy default, `linux2mqtt` will publish system metrics every 30 seconds. This can be changed using the `--interval` option.\n\n## Additional Metrics\n\n### Disk Usage\n\n`linux2mqtt` can publish disk usage metrics using the `du` option. Multiple `du` options can be specified to monitor different volumes. Each volume will present as a separate sensor in Home Assistant. The sensor state reports the percentage of total volume space consumed. Additional data (total volume size in bytes, free bytes, and used bytes) are accessible as state attributes on each sensor.\n\n`linux2mqtt --name Server1 -vvvvv --cpu=60 --vm --du='/var/spool' --du='/'`\n\n### Network Throughput\n\nNetwork throughput (amount of traffic) metrics are also available. Using one or more `--net` parameters, specify the interface name and the collection interval (as discussed in the CPU metrics documentation), separated by a comma. A separate MQTT topic is created for each interface and each will appear as a separate sensor in HA.\n\nThe sensor state equals average throughput of the interface during the collection interval (combining both transmit and receive) in kilobits per second. More detail is available in the state attributes, such as: individual TX and RX rates, number of packets, total bytes sent and received, etc. Except for TX and RX rates, all attribute values are total accumulated values since the interface was reset. Thus, expect to see very large numbers if the interface has been online a while.\n\n`linux2mqtt --name Server1 -vvvvv --interval 60 --net=eth0,15`\n\nThis will publish network throughput information about Server1's `eth0` interface to the MQTT broker once every 60 seconds. The sensor state will equal the average network throughput over the previous 15 seconds.\n\n### Thermal zones\n\n`linux2mqtt` can publish temperature metrics for thermal zones using the `temp` option. Each thermal zone will present as a separate sensor in Home Assistant. The sensor state reports the temperature in `\u00b0C`. Additional data is accessible as state attributes on each sensor.\n\n`linux2mqtt --name Server1 -vvvvv --cpu=60 --vm --temp`\n\n### Fan speeds\n\n`linux2mqtt` can publish fan speeds using the `fan` option. Each fan will present as a separate sensor in Home Assistant, but be aware this is only for monitoring which means it is not an actual fan entity but only presents itself as a sensor with **no** device class and **no** unit of measurements. The sensor state reports the fan speed in `RPM`. Additional data is accessible as state attributes on each sensor.\n\n`linux2mqtt --name Server1 -vvvvv --cpu=60 --vm --fan`\n\n## Compatibility\n\n`linux2mqtt` has been tested to work on CentOS, Ubuntu, and Debian (Raspberry Pi), even tough some features are not available everywhere. **Python 3.10 (or above) is recommended.**\n\n## Running in the Background (Daemonizing)\n\n`linux2mqtt` runs as a foreground task at the command prompt. In order to run in the program in the background, or automatically at boot, the process has to be daemonized. The easiest way to do this is on a UNIX-like OS (Linux/BSD) is with [Supervisor](http://supervisord.org/) or [systemd](https://systemd.io). Example Supervisor and service configuration file for `linux2mqtt` is included in the [/contrib/](https://github.com/miaucl/linux2mqtt/blob/master/contrib/) directory.\n\n## Using with Home Assistant (HA)\n\nOnce `linux2mqtt` is collecting data and publishing it to MQTT, it's rather trivial to use the data in Home Assistant.\n\nA few assumptions:\n\n* **Home Assistant is already configured to use a MQTT broker.** Setting up MQTT and HA is beyond the scope of this documentation. However, there are a lot of great tutorials on YouTube. An external broker (or as add-on) like [Mosquitto](https://mosquitto.org/) will need to be installed and the HA MQTT integration configured.\n* **The HA MQTT integration is configured to use `homeassistant` as the MQTT autodiscovery prefix.** This is the default for the integration and also the default for `linux2mqtt`. If you have changed this from the default, use the `--homeassistant-prefix` parameter to specify the correct one.\n* **You're not using TLS to connect to the MQTT broker.** Currently `linux2mqtt` only works with unencrypted connections. Username / password authentication can be specified with the `--username` and `--password` parameters, but TLS encryption is not yet supported.\n\nUsing the default prefix and a system name of `NUC` (the name of the server), the following state can be found in the \"States\" section of Developer Tools in HA:\n\n\n\n### Lovelace Dashboards\n\nTo visualize, use the excellent [mini-graph-card](https://github.com/kalkih/mini-graph-card) custom card for Lovelace dashboards. It's highly-customizable and fairly easy to make great looking charts in HA. Here is a very basic config example of using the metrics produced by `linux2mqtt` to display the past 12 hours of CPU and memory utilization on an Intel NUC server:\n\n```yaml\nentities:\n - entity: sensor.nuc_cpu\n name: CPU Utilization\n show_legend: true\n show_line: true\n show_points: false\n - entity: sensor.nuc_virtual_memory\n name: Memory Utilization\n show_legend: true\n show_line: true\n show_points: false\nhours_to_show: 12\nline_width: 2\nlower_bound: 0\nname: NUC System Metrics\npoints_per_hour: 6\nshow:\n labels: false\n labels_secondary: false\ntype: 'custom:mini-graph-card'\nupper_bound: 100\n```\n\n\n\n## Documentation\n\nUsing `mkdocs`, the documentation and reference is generated and available on [github pages](https://miaucl.github.io/linux2mqtt/).\n\n## Dev\n\nSetup the dev environment using VSCode, it is highly recommended.\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements_dev.txt\n```\n\nInstall [pre-commit](https://pre-commit.com)\n\n```bash\npre-commit install\n\n# Run the commit hooks manually\npre-commit run --all-files\n```\n\nFollowing VSCode integrations may be helpful:\n\n* [ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)\n* [mypy](https://marketplace.visualstudio.com/items?itemName=matangover.mypy)\n* [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)\n\n### Releasing\n\nIt is only possible to release a _final version_ on the `master` branch. For it to pass the gates of the `publish` workflow, it must have the same version in the `tag`, the `setup.cfg`, the `bring_api/__init__.py` and an entry in the `CHANGELOG.md` file.\n\nTo release a prerelease version, no changelog entry is required, but it can only happen on a feature branch (**not** `master` branch). Also, prerelease versions are marked as such in the github release page.\n\n## Credits\n\nThis is a detached fork from the repo <https://github.com/jamiebegin/linux2mqtt>, which does not seem to get evolved anymore.\n\n> This project is intended to be an alternative to the (very good) [Glances](https://github.com/nicolargo/glances) project. The primary design difference is that the Glances integration into Home Assistant relies on periodically polling a RESTful API. However, the pub/sub model of [MQTT](http://mqtt.org/)--which is already widely used in the home automation community--is an ideal fit for real-time reporting of this type of data. Additionally `linux2mqtt` can be very lightweight because it omits the GUI and alerting elements of Glances (which are redundant when used in conjunction with HA).\n\n# CHANGELOG\n\n## 1.2.0\n\n* Update version package identifier and bump setuptools\n* Bump psutil to 6\n* Fix mypy config\n\n## 1.1.0\n\n* Add temperature of thermal zones to metrics\n* Add fan speed of cooling devices to metrics\n* Update the discovery jsons for home assistant\n\n## 1.0.0\n\n* Initial version.\n",
"bugtrack_url": null,
"license": null,
"summary": "Send your linux stats and and events to mqtt and discovery them in home assistant.",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/miaucl/linux2mqtt"
},
"split_keywords": [
"mqtt",
" psutil",
" metrics",
" linux"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8886d841b2f5121bafc284da4eec2d8c255e08c838cde4ad92f3ae6ce453f1a2",
"md5": "b348a08efebe8257253ae352748c3fd3",
"sha256": "c04ee04ffe3c3869521a86e0ce64d59d6d351f04270a5f890ef7b3bef1aef0d9"
},
"downloads": -1,
"filename": "linux2mqtt-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b348a08efebe8257253ae352748c3fd3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 19359,
"upload_time": "2024-09-19T16:09:09",
"upload_time_iso_8601": "2024-09-19T16:09:09.505829Z",
"url": "https://files.pythonhosted.org/packages/88/86/d841b2f5121bafc284da4eec2d8c255e08c838cde4ad92f3ae6ce453f1a2/linux2mqtt-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "582dc3f9d25f9255fea8f20ba44a07d58c3076e5d067756b9251acfeb511487b",
"md5": "7d56a9093150bebe43917d1a376312fb",
"sha256": "f2de68762050ebdaa47bb7e987af64096c65eac3aeb610517956270b28a5f8f2"
},
"downloads": -1,
"filename": "linux2mqtt-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "7d56a9093150bebe43917d1a376312fb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 23574,
"upload_time": "2024-09-19T16:09:11",
"upload_time_iso_8601": "2024-09-19T16:09:11.070525Z",
"url": "https://files.pythonhosted.org/packages/58/2d/c3f9d25f9255fea8f20ba44a07d58c3076e5d067756b9251acfeb511487b/linux2mqtt-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-19 16:09:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miaucl",
"github_project": "linux2mqtt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "paho-mqtt",
"specs": []
},
{
"name": "jsons",
"specs": []
},
{
"name": "psutil",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "typing-extensions",
"specs": []
}
],
"lcname": "linux2mqtt"
}
JSON
