{"id":15481837,"url":"https://github.com/philipmay/smart-prom-next","last_synced_at":"2025-04-22T15:46:01.985Z","repository":{"id":37240817,"uuid":"504745279","full_name":"PhilipMay/smart-prom-next","owner":"PhilipMay","description":"S.M.A.R.T. Prometheus Metrics Exporter","archived":false,"fork":false,"pushed_at":"2023-07-24T05:29:16.000Z","size":298,"stargazers_count":18,"open_issues_count":17,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-17T04:19:33.408Z","etag":null,"topics":["docker","docker-image","grafana","harddisk","harddrive","kubernetes","metrics","monitoring","prometheus","prometheus-exporter","prometheus-metrics","smart"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PhilipMay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-06-18T04:44:09.000Z","updated_at":"2024-11-18T16:32:40.000Z","dependencies_parsed_at":"2023-12-05T04:47:00.700Z","dependency_job_id":null,"html_url":"https://github.com/PhilipMay/smart-prom-next","commit_stats":{"total_commits":183,"total_committers":3,"mean_commits":61.0,"dds":0.04371584699453557,"last_synced_commit":"276de886dcd0208fe9ca9c178c357cbc1311dd76"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipMay%2Fsmart-prom-next","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipMay%2Fsmart-prom-next/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipMay%2Fsmart-prom-next/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipMay%2Fsmart-prom-next/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhilipMay","download_url":"https://codeload.github.com/PhilipMay/smart-prom-next/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250271787,"owners_count":21403260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-image","grafana","harddisk","harddrive","kubernetes","metrics","monitoring","prometheus","prometheus-exporter","prometheus-metrics","smart"],"created_at":"2024-10-02T05:06:32.743Z","updated_at":"2025-04-22T15:46:01.938Z","avatar_url":"https://github.com/PhilipMay.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# S.M.A.R.T. Prometheus Metrics Exporter\n\n[![Docker images](https://img.shields.io/badge/Docker-image-blue)](https://github.com/PhilipMay/smart-prom-next/pkgs/container/smart-prom-next)\n[![pypi](https://img.shields.io/pypi/v/smart-prom-next.svg)](https://pypi.python.org/pypi/smart-prom-next)\\\n[![MIT License](https://img.shields.io/github/license/PhilipMay/smart-prom-next)](https://github.com/PhilipMay/smart-prom-next/blob/main/LICENSE)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/PhilipMay/smart-prom-next/blob/main/CODE_OF_CONDUCT.md)\n[![Python Version](https://img.shields.io/pypi/pyversions/smart-prom-next)](https://www.python.org)\n[![GitHub issues](https://img.shields.io/github/issues-raw/PhilipMay/smart-prom-next)](https://github.com/PhilipMay/smart-prom-next/issues)\\\n[![pytest status](https://github.com/PhilipMay/smart-prom-next/actions/workflows/pytest.yml/badge.svg)](https://github.com/PhilipMay/smart-prom-next/actions/workflows/pytest.yml)\n[![Static Code Checks status](https://github.com/PhilipMay/smart-prom-next/actions/workflows/static_checks.yml/badge.svg)](https://github.com/PhilipMay/smart-prom-next/actions/workflows/static_checks.yml)\\\n[![Docker build Debian image](https://github.com/PhilipMay/smart-prom-next/actions/workflows/docker-build-debian.yml/badge.svg)](https://github.com/PhilipMay/smart-prom-next/actions/workflows/docker-build-debian.yml)\n[![Docker build Alpine image](https://github.com/PhilipMay/smart-prom-next/actions/workflows/docker-build-alpine.yml/badge.svg)](https://github.com/PhilipMay/smart-prom-next/actions/workflows/docker-build-alpine.yml)\n[![trivy](https://github.com/PhilipMay/smart-prom-next/actions/workflows/trivy.yml/badge.svg)](https://github.com/PhilipMay/smart-prom-next/actions/workflows/trivy.yml)\n\nsmart-prom-next is a [Prometheus](https://prometheus.io/docs/introduction/overview/) metric exporter for\n[S.M.A.R.T.](https://en.wikipedia.org/wiki/S.M.A.R.T.) values of hard disks.\nPython and the Linux tool [smartctl](https://www.smartmontools.org/browser/trunk/smartmontools/smartctl.8.in)\nare used to read out the hard disk values. These are then exposed using\n[Prometheus Python Client](https://github.com/prometheus/client_python) over network port 9902.\n\nAccording to Wikipedia, the primary function of S.M.A.R.T. is to detect and report various indicators of drive\nreliability with the intent of anticipating imminent hardware failures.\n\nCurrently, smart-prom-next is available as a\n[docker image](https://github.com/PhilipMay/smart-prom-next/pkgs/container/smart-prom-next) and a\n[pypi package](https://pypi.org/project/smart-prom-next/).\n\nThe Docker image is built from the slim version of the [official Python Docker image](https://hub.docker.com/_/python),\nwhich uses [Debian Bullseye](https://www.debian.org/releases/bullseye/).\nIt is built for multiple platforms:\\\nlinux/386, linux/amd64, linux/arm/v5, linux/arm/v7, linux/arm64/v8\n\nThe second Docker option is also built from the\n[official Python Docker image](https://hub.docker.com/_/python),\nbut uses [Alpine](https://www.alpinelinux.org/).\nIt is built for multiple platforms:\\\nlinux/386, linux/amd64, linux/arm/v6, linux/arm/v7, linux/arm64/v8\n\n## Configuration Options / Environment Variables\n\nsmart-prom-next can be configured by the following environment variables:\n\n- `PROMETHEUS_METRIC_PORT` - port number over which the Prometheus metrics are exposed (default: 9902)\n- `SMART_INFO_READ_INTERVAL_SECONDS` - time interval in seconds at which the SMART values of the hard disk are read\n  (default: 60)\n\n## Docker / docker-compose\n\nThe images, which are based on Debian Bullseye slim, can be accessed using:\n`ghcr.io/philipmay/smart-prom-next:\u003cversion\u003e-slim-bullseye` or `ghcr.io/philipmay/smart-prom-next:latest`\n\nThe images, which are based on Alpine, can be accessed using: `ghcr.io/philipmay/smart-prom-next:\u003cversion\u003e-alpine`\n\nThe latest versions are visible in\n[smart-prom-next GitHub packages](https://github.com/PhilipMay/smart-prom-next/pkgs/container/smart-prom-next).\n\nBelow is an example of a complete minimal `docker-compose.yml`, how smart-prom-next can be used with [docker-compose](https://docs.docker.com/compose/):\n\n```yaml\nversion: \"3.0\"\nservices:\n  smart-prom-next:\n    # see https://github.com/PhilipMay/smart-prom-next/pkgs/container/smart-prom-next\n    image: ghcr.io/philipmay/smart-prom-next:latest\n    container_name: \"smart-prom-next\"\n    restart: unless-stopped\n    privileged: true\n    ports:\n      - 9902:9902\n```\n\nThe `privileged: true` permission is absolutely necessary so that smartctl can also access the hard disks from\nwithin the container.\n\n**Security note:** In the production environment, you should leave out the `ports:` part in the `docker-compose.yml`\nin the vast majority of configurations so that it is not visible to the outside. Instead, the container should\nbe assigned to a network in which the prometheus container is located. This looks like this:\n\n```yaml\n    networks:\n      - monitor\n```\n\nTo adjust the environment variables, the following settings can be added, for example:\n\n```yaml\n    environment:\n      - PROMETHEUS_METRIC_PORT=9009\n      - SMART_INFO_READ_INTERVAL_SECONDS=120\n```\n\n## Available Metrics\n\n### `smart_prom_smart_status_failed`\n\nThe SMART health status of the device. A value of 0 indicates a healthy state.\nA value of 1 means that the device has not passed the health check and there is a problem.\n\nList of labels used (description see below): \"device\", \"type\", \"model\", \"serial\"\n\n### `smart_prom_smartctl_exit_status`\n\nThe exit status (aka exit code or return code) of the `smartctl` tool.\nAny value other than zero indicates an issue.\nA more detailed description can be found in the EXIT STATUS chapter of the\n[smartctl man pages](https://www.smartmontools.org/browser/trunk/smartmontools/smartctl.8.in).\n\nList of labels used (description see below): \"device\", \"type\", \"model\", \"serial\"\n\n### `smart_prom_smart_info`\n\nThe SMART Attributes.\nA more detailed description can be found in the `-A, --attributes` chapter of the\n[smartctl man pages](https://www.smartmontools.org/browser/trunk/smartmontools/smartctl.8.in).\n\nList of labels used (description see below): \"device\", \"type\", \"model\", \"serial\", \"attr_name\", \"attr_type\", \"attr_id\"\n\n### `smart_prom_nvme_smart_info`\n\n[NVMe](https://en.wikipedia.org/wiki/NVM_Express) specific SMART attributes obtained from\nthe SMART/Health Information log.\nA more detailed description can be found in the `-A, --attributes` chapter of the\n[smartctl man pages](https://www.smartmontools.org/browser/trunk/smartmontools/smartctl.8.in).\n\nList of labels used (description see below): \"device\", \"type\", \"model\", \"serial\", \"attr_name\"\n\n### `smart_prom_scsi_smart_info`\n\n[SCSI](https://en.wikipedia.org/wiki/SCSI) specific SMART attributes obtained from\nthe SMART/Health Information log.\nA more detailed description can be found in the `-A, --attributes` chapter of the\n[smartctl man pages](https://www.smartmontools.org/browser/trunk/smartmontools/smartctl.8.in).\n\nList of labels used (description see below): \"device\", \"type\", \"model\", \"serial\", \"attr_name\", \"attr_type\"\n\n### `smart_prom_temperature`\n\nThe temperature values of the device. These include not only the current temperature but also other values.\n\nList of labels used (description see below): \"device\", \"type\", \"model\", \"serial\", \"temperature_type\"\n\n### `smart_prom_scrape_iterations_total`\n\nCounter how often the SMART values were scraped.\n\n## Metrics Label\n\nIn this project, we use different labels on the metrics. These are described here:\n\n- `device` - device file, e.g.: `/dev/nvme0`, `/dev/sda`\n- `type` -  type of the device, e.g.: `ata`, `nvme`, `usbjmicron`\n- `model` - model name, e.g.: `KXG6AZNV512G TOSHIBA`, `WDC WD3200BEVT-60ZCT0`\n- `serial` - serial number, e.g.: `WD-WXE708D44703`, `Y9SF71LHFWZL`\n- `temperature_type` - type of the temperature value, e.g.: `current`, `power_cycle_max`, `lifetime_max`, `op_limit_max`\n- `attr_name` - SMART attribute name, e.g.: `raw_read_error_rate`, `reallocated_sector_ct`, `critical_warning`\n- `attr_id` - SMART attribute id, e.g.: `1`, `3`, `4`\n- `attr_type` - type of the respective SMART attribute - value is one of this: `value`, `worst`, `thresh`, `raw`, `failed_now`, `failed_past` -\n  a detailed description can be found in the `-A, --attributes` chapter of the\n  [smartctl man pages](https://www.smartmontools.org/browser/trunk/smartmontools/smartctl.8.in)\n\n## Prometheus Alerts\n\nBased on the metrics, [Prometheus alerts](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)\ncan be defined. Below are a few suggestions for `prometheus_rules.yml`:\n\n```yaml\ngroups:\n  - name: alert_rules\n    rules:\n  \n      - alert: DiskFailing\n        expr: smart_prom_smart_info{attr_type=\"failed_now\"} == 1\n        labels:\n          severity: critical\n        annotations:\n          summary: \"disk failing\"\n\n      - alert: DiskTemperatureHigh\n        expr: smart_prom_temperature{temperature_type=\"current\"} \u003e 50\n        labels:\n          severity: warning\n        annotations:\n          summary: \"disk temperature \u003e 50\"\n\n      - alert: SMARTStatusFailing\n        expr: smart_prom_smart_status_failed == 1\n        labels:\n          severity: critical\n        annotations:\n          summary: \"SMART status failing\"\n```\n\n## Release News\n\n**Here you can find the latest versions of the software:**\n\n- [docker image (Debian and Alpine)](https://github.com/PhilipMay/smart-prom-next/pkgs/container/smart-prom-next)\n- [pypi package](https://pypi.org/project/smart-prom-next/)\n- [GitHub releases](https://github.com/PhilipMay/smart-prom-next/releases)\n\n**Important news and features in the releases:**\n\n- add additional Alpine based image [#40](https://github.com/PhilipMay/smart-prom-next/issues/40) -\n  version `0.0.4` at 2022-07-28\n- add -slim-bullseye suffix to image [#44](https://github.com/PhilipMay/smart-prom-next/issues/44) -\n  version `0.0.4` at 2022-07-28\n- improve logs with \"error\" and \"warning\" prefix [#43](https://github.com/PhilipMay/smart-prom-next/issues/43) -\n  version `0.0.4` at 2022-07-28\n- [add scsi disk handling](https://github.com/PhilipMay/smart-prom-next/issues/12) - thanks to\n  [Jopaul-John](https://github.com/Jopaul-John) - version `0.0.3` at 2022-07-20\n- breaking change on `smart_prom_nvme_smart_info` - version `0.0.2` at 2022-06-23\n- additional `smart_prom_scrape_iterations_total` metric - version `0.0.2` at 2022-06-23\n- first pre-release - pre-release version `0.0.1rc9` at 2022-06-20\n\n## Special Thanks\n\nA special thanks goes to the following contributors:\n\n- [@Jopaul-John](https://github.com/Jopaul-John) for his help in\n  [adding scsi disk handling](https://github.com/PhilipMay/smart-prom-next/issues/12)\n- [Michal Harakal (@michalharakal)](https://github.com/michalharakal)\n  for the first PR of this project to\n  [improve the docker-compose example](https://github.com/PhilipMay/smart-prom-next/pull/29)\n- [Diego Heras (@ngosang)](https://github.com/ngosang) for his\n  [help in adding the Alpine image](https://github.com/PhilipMay/smart-prom-next/issues/40#issuecomment-1197198019)\n\n## Licensing\n\nCopyright (c) 2022 Philip May\n\nLicensed under the **MIT License** (the \"License\"); you may not use this file except in compliance with the License.\nYou may obtain a copy of the License by reviewing the file\n[LICENSE](https://github.com/PhilipMay/smart-prom-next/blob/main/LICENSE) in the repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilipmay%2Fsmart-prom-next","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilipmay%2Fsmart-prom-next","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilipmay%2Fsmart-prom-next/lists"}