{ "info": { "author": "Jonas Wielicki", "author_email": "jonas.wielicki@cloudandheat.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Intended Audience :: System Administrators", "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)", "Operating System :: POSIX :: Linux", "Operating System :: Unix", "Programming Language :: Python :: 3", "Topic :: System :: Monitoring" ], "description": "S.M.A.R.T. exporter for Prometheus\n##################################\n\nThis is a `Prometheus Exporter `_ which exports S.M.A.R.T. metrics.\n\nCore Features\n=============\n\n* Secure: only the absolute necessary part of the code runs as root, in a separate process\n* No guessing: re-uses the device database from the `check_smart_attributes`_ nagios check.\n\nArchitecture\n============\n\nWe want to avoid having a service running as root exposed to the network. This is why the S.M.A.R.T. exporter is split in two parts:\n\n1. a helper which runs as root (``smart_exporter_helper``)\n2. the HTTP server which serves the data (``prometheus_smart_exporter``)\n\nThe helper runs as a service listening on UNIX socket (ideally managed by systemd, but can also be managed by the helper itself). When a client connects to the socket, the helper reads S.M.A.R.T. metrics and sends them to the client as serialised Python dict wrapped in a simple binary format.\n\nThe exporter listens on HTTP and when asked to export data, it connects to the UNIX socket and receives the current S.M.A.R.T. metrics. All interpretation, filtering and Prometheus-specific formatting of the data is done in the exporter and as unprivilegued user.\n\nSocket Protocol\n---------------\n\nThe binary protocol is dead-simple:\n\n+-----------+-------------------+----------------------------------------------------------+\n|Byte range |Type |Usage |\n+===========+===================+==========================================================+\n|0 |unsigned |Protocol Version. Must be ``1``. |\n+-----------+-------------------+----------------------------------------------------------+\n|1-8 |unsigned |Length of the data in bytes |\n+-----------+-------------------+----------------------------------------------------------+\n|9..end |UTF-8 encoded text |``repr()`` of python dict containing the S.M.A.R.T. data. |\n+-----------+-------------------+----------------------------------------------------------+\n\n\nSecurity\n--------\n\nSince part of this code runs as root, this deserves its own section. The helper is the only process which is supposed to run as root. Do **not** run the exporter itself as root.\n\nThe helper is less than 300 lines of nearly dependency-free (the exception are the systemd helpers for socket activation and journalling) python, making it easy to audit. It does not accept input from its clients (in fact, it immediately closes the receiving direction of the socket once it is accepted).\n\n\nInstallation\n============\n\nInstall via PyPI:\n\n.. code-block:: sh\n\n pip3 install prometheus_smart_exporter\n\nInstallation via PyPI does *not* install any system-wide configuration. You need to do that yourself.\n\n\nConfiguration\n=============\n\nServices and Sockets\n--------------------\n\nIt is recommended to use systemd to manage the UNIX socket for the helper. It allows you fine control over the user, group and mode of the socket, thus allowing to expose the socket only to the exporter process. In addition, at allows for seamless restarts of the helper service.\n\nExample service files for use with systemd are included in the `git repository`_.\n\n.. _device-db:\n\nS.M.A.R.T. device database\n--------------------------\n\nThis exporter uses a device database in the same format as the famous nagios `check_smart_attributes`_ does. If you already use or have used the ``check_smart_attributes``, you can simply continue using your device database. Otherwise, you will find a device database in the linked github repository.\n\nThe only information used from the device DB is the information whether a ``RAW_VALUE`` or a ``VALUE`` should be exported. At some point, it may be configurable to only export metrics for values which have thresholds and/or perfs set.\n\n\n.. _attr-mapping:\n\nAttribute Mapping\n-----------------\n\nAn additional JSON file specifies how S.M.A.R.T. attributes are mapped to Prometheus metric names. It defines rules which, based on the S.M.A.R.T. attribute ID and name, decide the type and name of the Prometheus metric.\n\nThe basic format is the following:\n\n.. code-block:: json\n\n {\n \"generic\": [\n < rules ... >\n ]\n }\n\nEach ``rule`` looks like this:\n\n.. code-block:: json\n\n {\n \"id\": < integer >,\n \"match\": < regular expression as string >,\n \"name\": < string >,\n \"type\": < \"counter\" or \"gauge\" >\n }\n\n``\"id\"``\n is mandatory and the S.M.A.R.T. attribute ID for which this rule is used\n``\"match\"``\n is an optional regular expression. Only if the name of the attribute matches the regular expression, the rule is applied.\n``\"name\"``\n the name of the Prometheus metric to use. All metric names are automatically prefixed with ``smart_``; the prefix must not be included in the ``\"name\"`` attribute.\n``\"type\"``\n the type of the Prometheus metric to use (generally ``\"gauge\"`` or ``\"counter\"``).\n\nA default attribute mapping is included in the package itself. Pull requests for additional rules are welcome.\n\nHelper\n------\n\nThe helper is configured using command line arguments only.\n\n.. code-block::\n\n usage: smart_exporter_helper [-h] [--socket-path SOCKET_PATH]\n [--timeout TIMEOUT] [-v]\n\n optional arguments:\n -h, --help show this help message and exit\n --socket-path SOCKET_PATH\n Path at which the unix socket will be created.\n Required if the process is not started via systemd\n socket activation.\n --timeout TIMEOUT Time in seconds to wait between connections. Defaults\n to infinity.\n -v\n\n``--timeout``\n specifies the time for which the service stays alive after finishing the last request. This can be used to help conserve memory at the cost of measurement latency and CPU/disk-IO.\n\n``--socket-path``\n If systemd socket activation is not used, this argument must be given to specify at which location the socket shall be created. If a socket is already present at that location, it is unlinked at startup and replaced with a fresh socket. In general, it is recommended to use systemd with socket activation instead.\n\nHTTP Exporter\n-------------\n\nThe HTTP exporter is configured using the aforementioned JSON files and command line arguments.\n\n.. code-block::\n\n usage: prometheus_smart_exporter [-h] [--device-db DEVICE_DB]\n [--attr-mapping ATTR_MAPPING] [-v]\n [--journal] [-p PORT] [-a ADDR]\n socket\n\n positional arguments:\n socket Path to UNIX socket where the helper listens\n\n optional arguments:\n -h, --help show this help message and exit\n --device-db DEVICE_DB\n Device database in JSON format (default:\n /usr/share/ch-monitoring-smart-data/devices.json)\n --attr-mapping ATTR_MAPPING\n Attribute mapping in JSON format (default: <...>)\n -v Increase verbosity (up to -vvv)\n --journal Log to systemd journal\n -p PORT, --listen-port PORT\n Port number to bind to (default: 9257)\n -a ADDR, --listen-address ADDR\n Address to bind to (default: 127.0.0.1)\n\n``--device-db``\n path to the S.M.A.R.T. device database (see above)\n\n``--attr-mapping``\n path to the attribute map attr-mapping (see above). By default, the attribute map delivered with the package is used.\n\n``--journal``\n enable logging to the systemd journal. By default, logs go to standard output.\n\n``--listen-port``\n configure the TCP port to bind to\n\n``--listen-address``\n configure the TCP address to bind to\n\n``socket``\n path to the UNIX socket where the helper listens\n\n\n.. _check_smart_attributes: https://github.com/thomas-krenn/check_smart_attributes\n.. _git repository: https://github.com/cloudandheat/prometheus_smart_exporter", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/cloudandheat/prometheus_smart_exporter", "keywords": "prometheus smart monitoring hdd ssd", "license": "", "maintainer": "", "maintainer_email": "", "name": "prometheus-smart-exporter", "package_url": "https://pypi.org/project/prometheus-smart-exporter/", "platform": "", "project_url": "https://pypi.org/project/prometheus-smart-exporter/", "project_urls": { "Homepage": "https://github.com/cloudandheat/prometheus_smart_exporter" }, "release_url": "https://pypi.org/project/prometheus-smart-exporter/0.2.2/", "requires_dist": null, "requires_python": "", "summary": "S.M.A.R.T. exporter for Prometheus", "version": "0.2.2" }, "last_serial": 3027886, "releases": { "0.2.2": [ { "comment_text": "", "digests": { "md5": "6127fffeadfa024de356c514d3cc91ce", "sha256": "027668092e83c4b126051fdd25891f4613b1630eb4c15ba76ef3220fa80b451e" }, "downloads": -1, "filename": "prometheus_smart_exporter-0.2.2.tar.gz", "has_sig": true, "md5_digest": "6127fffeadfa024de356c514d3cc91ce", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 28392, "upload_time": "2017-07-17T06:54:40", "url": "https://files.pythonhosted.org/packages/76/d8/3a039bfd678287c0ba99450297071a146a638e6a312f6590a2537ec6b3cf/prometheus_smart_exporter-0.2.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "6127fffeadfa024de356c514d3cc91ce", "sha256": "027668092e83c4b126051fdd25891f4613b1630eb4c15ba76ef3220fa80b451e" }, "downloads": -1, "filename": "prometheus_smart_exporter-0.2.2.tar.gz", "has_sig": true, "md5_digest": "6127fffeadfa024de356c514d3cc91ce", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 28392, "upload_time": "2017-07-17T06:54:40", "url": "https://files.pythonhosted.org/packages/76/d8/3a039bfd678287c0ba99450297071a146a638e6a312f6590a2537ec6b3cf/prometheus_smart_exporter-0.2.2.tar.gz" } ] }