# pySMART-exporter
Copyright (C) 2021 Rafael Leira, Naudit HPCN S.L.
`pySMART-exporter` is a Python Prometheus exporter for collecting and exposing S.M.A.R.T. metrics of storage devices. It leverages the [pySMART library](https://github.com/truenas/py-SMART) and integrates Prometheus client library functionalities for HTTP publication or file-based metric exports.
---
## Features
- Collects S.M.A.R.T. metrics from storage devices.
- Supports Prometheus integration via HTTP or text-based node collector files.
- Includes support for various storage interfaces, including NVMe attributes and diagnostics.
---
## Installation
The `pySMART-exporter` can be installed via PyPI:
```bash
python -m pip install pySMART-exporter
```
Ensure that `smartctl` from the `smartmontools` package is installed, as it is a prerequisite. For most Linux distributions, use your package manager:
```bash
sudo apt-get install smartmontools
# or
sudo yum install smartmontools
```
---
## Usage
The exporter supports two modes: **server mode** (HTTP) and **file mode** (node exporter textfile). It should run as a privileged user to access disk information.
### Server Mode
To run the exporter in server mode, execute the following command:
```bash
pysmart_exporter -l 0.0.0.0:9099
```
Then configure Prometheus to scrape metrics from the endpoint.
### File Mode
To generate a one-time metric file for use with a Prometheus node exporter:
```bash
pysmart_exporter -f /path/to/output/file.txt -1
```
To continuously generate metric files at a set interval (e.g., 60 seconds):
```bash
pysmart_exporter -f /path/to/output/file.txt -i 60
```
---
## Example Metrics Output
Below is a sample of the metrics exposed by `pySMART-exporter`:
```prometheus
# HELP pysmart_info PySMART metric info
# TYPE pysmart_info gauge
pysmart_info{device="nvme0",firmware="ADHA0101",interface="nvme",model="KBG30ZMV256G TOSHIBA",rotation="None",serial="*********12P",size="256000000000",size_raw="256 GB",smart_capable="True",smart_enabled="True",ssd="True"} 1.0
# HELP pysmart_assessment PySMART metric assessment
# TYPE pysmart_assessment gauge
pysmart_assessment{device="nvme0",interface="nvme",pysmart_assessment="PASS"} 1.0
# HELP pysmart_temperature PySMART metric temperature
# TYPE pysmart_temperature gauge
pysmart_temperature{device="nvme0",interface="nvme"} 44.0
# HELP pysmart_size PySMART metric size
# TYPE pysmart_size gauge
pysmart_size{device="nvme0",interface="nvme"} 2.56e+011
# HELP pysmart_test_capabilities PySMART metric test_capabilities
# TYPE pysmart_test_capabilities gauge
pysmart_test_capabilities{device="nvme0",interface="nvme",pysmart_test_capabilities="short"} 1.0
```
---
## CLI Options
| Option | Description |
|-----------------------|--------------------------------------------------------------------------------------------------|
| `-f`, `--textfile-name` | Path to the file where metrics will be stored for node collection. |
| `-l`, `--listen` | Host and port to listen on in HTTP server mode (e.g., `0.0.0.0:9417`). |
| `-i`, `--interval` | Interval (in seconds) between metric updates. Default: `60`. |
| `-1`, `--oneshot` | Run only once and exit (useful for cron jobs). |
| `-q`, `--quiet` | Suppress error messages and warnings. |
| `--include` | Comma-separated list of devices to include (e.g., `nvme0,/dev/sda`). |
| `--exclude` | Comma-separated list of devices to exclude. |
| `--metric-prefix` | Custom prefix for metrics. Default: `pysmart`. |
| `--metrics` | Comma-separated list of specific metrics to export (e.g., `temperature,size,assessment_passed`).|
---
## Metrics
| **Metric Name** | **Type** | **Description** | **Labels** |
|---|---|---|---|
|`pysmart_info`|`info`|General information about the disk, including model, firmware, size, and other static attributes.|`device`, `interface`, `model`, `serial`, `firmware`, `rotation`, `size_raw`, `size`, `ssd`, `smart_capable`, `smart_enabled`, `vendor`, `sector_size`, and more.|
|`pysmart_assessment_passed`|`gauge`|Assessment of the disk's health. `1` for PASS, `0` otherwise.|`device`, `interface`|
|`pysmart_temperature`|`gauge`|Current temperature of the disk in Celsius.|`device`, `interface`|
|`pysmart_size`|`gauge`|Disk size in bytes.|`device`, `interface`|
|`pysmart_attribute_value`|`gauge`|SMART attribute values such as error counts, read/write metrics, etc.|`device`, `name` (attribute name), `num`, `type`, `flags`, `updated`, `whenfailed`, and more depending on attribute.|
|`pysmart_attribute_thresh`|`gauge`|Threshold values for SMART attributes.|Similar to `pysmart_attribute_value`|
|`pysmart_attribute_worst`|`gauge`|The worst recorded value for a given SMART attribute.|Similar to `pysmart_attribute_value`|
|`pysmart_attribute_raw`|`gauge`|The raw value for a SMART attribute.|Similar to `pysmart_attribute_value`|
|`pysmart_diagnostics_*`|`gauge`|Disk diagnostic statistics, including errors and other health-related data.|`device`, `interface`|
|`pysmart_test_capabilities`|`state`|Types of self-tests supported by the disk (e.g., short, long, offline).|`device`, `interface`|
|`pysmart_test`|`gauge`|Details about completed or pending disk self-tests.|`device`, `type` (test type), `status`, `hours`, `num`, and other self-test details.|
---
## Installation
``pySMART-exporter`` is available on PyPI and installable via ``pip``::
python -m pip install pySMART-exporter
The only external (non-python) dependency is the ``smartctl`` component of the smartmontools package. This should be pre-installed in most Linux distributions, or it can be obtained through your package manager. Likely one of the following::
apt-get install smartmontools
or
yum install smartmontools
## License
This program is distributed under the terms of the license specified in the [LICENSE](./LICENSE) file.
---
## References
- [pySMART Library](https://github.com/truenas/py-SMART)
- [Prometheus Documentation](https://prometheus.io/docs/)
- [SMART Monitoring Tools](https://www.smartmontools.org/)
Raw data
{
"_id": null,
"home_page": null,
"name": "pySMART-exporter",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "prometheus, SMART, exporter, monitoring",
"author": null,
"author_email": "Rafael Leira <rafael.leira@naudit.es>",
"download_url": "https://files.pythonhosted.org/packages/4c/64/fd9b0c63c29b2f51d4dbca8fa1d8f9e5e1c144ae8cf4177acb9c600d2fa1/pysmart_exporter-0.4.0.tar.gz",
"platform": null,
"description": " \n# pySMART-exporter\n\n\n\n\n\n\n\n\nCopyright (C) 2021 Rafael Leira, Naudit HPCN S.L.\n\n`pySMART-exporter` is a Python Prometheus exporter for collecting and exposing S.M.A.R.T. metrics of storage devices. It leverages the [pySMART library](https://github.com/truenas/py-SMART) and integrates Prometheus client library functionalities for HTTP publication or file-based metric exports.\n\n---\n\n## Features\n\n- Collects S.M.A.R.T. metrics from storage devices.\n- Supports Prometheus integration via HTTP or text-based node collector files.\n- Includes support for various storage interfaces, including NVMe attributes and diagnostics.\n\n---\n\n## Installation\n\nThe `pySMART-exporter` can be installed via PyPI:\n\n```bash\npython -m pip install pySMART-exporter\n```\n\nEnsure that `smartctl` from the `smartmontools` package is installed, as it is a prerequisite. For most Linux distributions, use your package manager:\n\n```bash\nsudo apt-get install smartmontools\n\n# or\n\nsudo yum install smartmontools\n```\n\n---\n\n## Usage\n\nThe exporter supports two modes: **server mode** (HTTP) and **file mode** (node exporter textfile). It should run as a privileged user to access disk information.\n\n### Server Mode\n\nTo run the exporter in server mode, execute the following command:\n\n```bash\npysmart_exporter -l 0.0.0.0:9099\n```\n\nThen configure Prometheus to scrape metrics from the endpoint.\n\n### File Mode\n\nTo generate a one-time metric file for use with a Prometheus node exporter:\n\n```bash\npysmart_exporter -f /path/to/output/file.txt -1\n```\n\nTo continuously generate metric files at a set interval (e.g., 60 seconds):\n\n```bash\npysmart_exporter -f /path/to/output/file.txt -i 60\n```\n\n---\n\n## Example Metrics Output\n\nBelow is a sample of the metrics exposed by `pySMART-exporter`:\n\n```prometheus\n# HELP pysmart_info PySMART metric info\n# TYPE pysmart_info gauge\npysmart_info{device=\"nvme0\",firmware=\"ADHA0101\",interface=\"nvme\",model=\"KBG30ZMV256G TOSHIBA\",rotation=\"None\",serial=\"*********12P\",size=\"256000000000\",size_raw=\"256 GB\",smart_capable=\"True\",smart_enabled=\"True\",ssd=\"True\"} 1.0\n# HELP pysmart_assessment PySMART metric assessment\n# TYPE pysmart_assessment gauge\npysmart_assessment{device=\"nvme0\",interface=\"nvme\",pysmart_assessment=\"PASS\"} 1.0\n# HELP pysmart_temperature PySMART metric temperature\n# TYPE pysmart_temperature gauge\npysmart_temperature{device=\"nvme0\",interface=\"nvme\"} 44.0\n# HELP pysmart_size PySMART metric size\n# TYPE pysmart_size gauge\npysmart_size{device=\"nvme0\",interface=\"nvme\"} 2.56e+011\n# HELP pysmart_test_capabilities PySMART metric test_capabilities\n# TYPE pysmart_test_capabilities gauge\npysmart_test_capabilities{device=\"nvme0\",interface=\"nvme\",pysmart_test_capabilities=\"short\"} 1.0\n```\n\n---\n\n## CLI Options\n\n| Option | Description |\n|-----------------------|--------------------------------------------------------------------------------------------------|\n| `-f`, `--textfile-name` | Path to the file where metrics will be stored for node collection. |\n| `-l`, `--listen` | Host and port to listen on in HTTP server mode (e.g., `0.0.0.0:9417`). |\n| `-i`, `--interval` | Interval (in seconds) between metric updates. Default: `60`. |\n| `-1`, `--oneshot` | Run only once and exit (useful for cron jobs). |\n| `-q`, `--quiet` | Suppress error messages and warnings. |\n| `--include` | Comma-separated list of devices to include (e.g., `nvme0,/dev/sda`). |\n| `--exclude` | Comma-separated list of devices to exclude. |\n| `--metric-prefix` | Custom prefix for metrics. Default: `pysmart`. |\n| `--metrics` | Comma-separated list of specific metrics to export (e.g., `temperature,size,assessment_passed`).|\n\n---\n\n## Metrics\n\n| **Metric Name** | **Type** | **Description** | **Labels** |\n|---|---|---|---|\n|`pysmart_info`|`info`|General information about the disk, including model, firmware, size, and other static attributes.|`device`, `interface`, `model`, `serial`, `firmware`, `rotation`, `size_raw`, `size`, `ssd`, `smart_capable`, `smart_enabled`, `vendor`, `sector_size`, and more.|\n|`pysmart_assessment_passed`|`gauge`|Assessment of the disk's health. `1` for PASS, `0` otherwise.|`device`, `interface`|\n|`pysmart_temperature`|`gauge`|Current temperature of the disk in Celsius.|`device`, `interface`|\n|`pysmart_size`|`gauge`|Disk size in bytes.|`device`, `interface`|\n|`pysmart_attribute_value`|`gauge`|SMART attribute values such as error counts, read/write metrics, etc.|`device`, `name` (attribute name), `num`, `type`, `flags`, `updated`, `whenfailed`, and more depending on attribute.|\n|`pysmart_attribute_thresh`|`gauge`|Threshold values for SMART attributes.|Similar to `pysmart_attribute_value`|\n|`pysmart_attribute_worst`|`gauge`|The worst recorded value for a given SMART attribute.|Similar to `pysmart_attribute_value`|\n|`pysmart_attribute_raw`|`gauge`|The raw value for a SMART attribute.|Similar to `pysmart_attribute_value`|\n|`pysmart_diagnostics_*`|`gauge`|Disk diagnostic statistics, including errors and other health-related data.|`device`, `interface`|\n|`pysmart_test_capabilities`|`state`|Types of self-tests supported by the disk (e.g., short, long, offline).|`device`, `interface`|\n|`pysmart_test`|`gauge`|Details about completed or pending disk self-tests.|`device`, `type` (test type), `status`, `hours`, `num`, and other self-test details.| \n\n ---\n\n## Installation\n\n``pySMART-exporter`` is available on PyPI and installable via ``pip``::\n\n python -m pip install pySMART-exporter\n\nThe only external (non-python) dependency is the ``smartctl`` component of the smartmontools package. This should be pre-installed in most Linux distributions, or it can be obtained through your package manager. Likely one of the following::\n\n apt-get install smartmontools\n or\n yum install smartmontools\n\n\n## License\n\nThis program is distributed under the terms of the license specified in the [LICENSE](./LICENSE) file.\n\n---\n\n## References\n\n- [pySMART Library](https://github.com/truenas/py-SMART)\n\n- [Prometheus Documentation](https://prometheus.io/docs/)\n\n- [SMART Monitoring Tools](https://www.smartmontools.org/)\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A Prometheus PySMART exporter",
"version": "0.4.0",
"project_urls": {
"homepage": "https://repo1.naudit.es/theseus/pysmart-exporter"
},
"split_keywords": [
"prometheus",
" smart",
" exporter",
" monitoring"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c2bfe8bf322db3c188485048c3f8c12c53c22656cb5d9b60faf6a74b0e68382",
"md5": "abfdee15a7219d59be035bed1a6c30d5",
"sha256": "f71c8607f68393fb8e76591c423115bd5cbfd12b6c16a5190dbf2bb472104a47"
},
"downloads": -1,
"filename": "pySMART_exporter-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "abfdee15a7219d59be035bed1a6c30d5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10553,
"upload_time": "2024-11-20T15:30:22",
"upload_time_iso_8601": "2024-11-20T15:30:22.717162Z",
"url": "https://files.pythonhosted.org/packages/3c/2b/fe8bf322db3c188485048c3f8c12c53c22656cb5d9b60faf6a74b0e68382/pySMART_exporter-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4c64fd9b0c63c29b2f51d4dbca8fa1d8f9e5e1c144ae8cf4177acb9c600d2fa1",
"md5": "08e98a037b12ca9c2e64495a8afb761b",
"sha256": "057d0ba988f223fa3d2aab168dd6abfb77eb13b4f2241d20ec04086147231794"
},
"downloads": -1,
"filename": "pysmart_exporter-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "08e98a037b12ca9c2e64495a8afb761b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10343,
"upload_time": "2024-11-20T15:30:24",
"upload_time_iso_8601": "2024-11-20T15:30:24.536829Z",
"url": "https://files.pythonhosted.org/packages/4c/64/fd9b0c63c29b2f51d4dbca8fa1d8f9e5e1c144ae8cf4177acb9c600d2fa1/pysmart_exporter-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 15:30:24",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pysmart-exporter"
}
JSON