{"id":16817196,"url":"https://github.com/ssddanbrown/wirestat","last_synced_at":"2025-11-06T03:30:25.757Z","repository":{"id":47873493,"uuid":"515540958","full_name":"ssddanbrown/wirestat","owner":"ssddanbrown","description":"This project has moved to Codeberg","archived":true,"fork":false,"pushed_at":"2023-04-20T00:26:41.000Z","size":68,"stargazers_count":87,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-27T12:23:43.765Z","etag":null,"topics":["go","golang","linux","monitoring","systemd"],"latest_commit_sha":null,"homepage":"https://codeberg.org/danb/wirestat","language":"Go","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/ssddanbrown.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/funding.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ssddanbrown"],"ko_fi":"ssddanbrown"}},"created_at":"2022-07-19T10:38:24.000Z","updated_at":"2024-10-03T21:24:20.000Z","dependencies_parsed_at":"2024-06-19T09:17:16.801Z","dependency_job_id":"4728bea9-801b-45a7-a055-e38d64a27af1","html_url":"https://github.com/ssddanbrown/wirestat","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"36ccea22f0109cb055c8370585c822e35da246d8"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssddanbrown%2Fwirestat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssddanbrown%2Fwirestat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssddanbrown%2Fwirestat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssddanbrown%2Fwirestat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ssddanbrown","download_url":"https://codeload.github.com/ssddanbrown/wirestat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239479543,"owners_count":19645760,"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":["go","golang","linux","monitoring","systemd"],"created_at":"2024-10-13T10:46:29.513Z","updated_at":"2025-11-06T03:30:25.719Z","avatar_url":"https://github.com/ssddanbrown.png","language":"Go","funding_links":["https://github.com/sponsors/ssddanbrown","https://ko-fi.com/ssddanbrown"],"categories":[],"sub_categories":[],"readme":"# wirestat\n\nThis is a simple application that, when running on a machine, will output core system metrics in a JSON response at a HTTP endpoint. Rules can be defined against these metrics for alerting. The existence of any alerts will cause the JSON response to be served with a HTTP error status code. \n\nThe application does not outwardly send any notifications (email, sms etc..) itself but it can be paired with a low cost, [or even self-hosted](https://github.com/louislam/uptime-kuma), website monitoring tool to form a simple system monitoring \u0026 alerting setup.\n\n## Example JSON Response\n\nA typical JSON response from the application, with active rules and alerts, looks like this:\n\n```json\n{\n  \"alerts\": [\n    \"Root drive is almost full\"\n  ],\n  \"rules\": {\n    \"CPU is over 50%\": {\n      \"property\": \"cpu.all_active_percent\",\n      \"operator\": \"\\u003e=\",\n      \"value\": 50\n    },\n    \"Memory is over 70%\": {\n      \"property\": \"memory.used_percent\",\n      \"operator\": \"\\u003e\",\n      \"value\": 70\n    },\n    \"Root drive is almost full\": {\n      \"property\": \"filesystem./dev/nvme0n1p3.used_percent\",\n      \"operator\": \"\\u003e\",\n      \"value\": 80\n    }\n  },\n  \"metrics\": {\n    \"cpu.all_active_percent\": 5,\n    \"cpu.cpu0_active_percent\": 2,\n    \"cpu.cpu1_active_percent\": 5,\n    \"cpu.cpu2_active_percent\": 3,\n    \"cpu.cpu3_active_percent\": 8,\n    \"filesystem./dev/nvme0n1p3.available\": 10955,\n    \"filesystem./dev/nvme0n1p3.capacity\": 230107,\n    \"filesystem./dev/nvme0n1p3.used\": 219152,\n    \"filesystem./dev/nvme0n1p3.used_percent\": 96,\n    \"memory.available\": 9550,\n    \"memory.buffers\": 442,\n    \"memory.cached\": 4047,\n    \"memory.free\": 5333,\n    \"memory.swap_cached\": 0,\n    \"memory.swap_free\": 10589,\n    \"memory.swap_total\": 10589,\n    \"memory.swap_used\": 0,\n    \"memory.swap_used_percent\": 0,\n    \"memory.total\": 16585,\n    \"memory.used\": 6760,\n    \"memory.used_percent\": 40,\n    \"uptime.days\": 12,\n    \"uptime.hours\": 2,\n    \"uptime.minutes\": 9,\n    \"uptime.seconds\": 4\n  },\n  \"metrics_updated_at\": \"2022-07-22T12:44:56.39827463+01:00\"\n}\n```\n\n## Advisory \u0026 Compatibility\n\nThis application has been thrown together, primarily for my own use, with little serious experience of golang, and likely contains bugs. For some stats, such as disk info, command output is read (`df command`) and parsed. It has been tested on the following systems:\n\n- Ubuntu 20.04/22.04 (x86_64)\n- Fedora 36/37/38 (x86_64)\n\nOnly Linux x86_64 systems are supported at this time. \nI would be willing to support other linux architectures, upon request \u0026 PR \u0026 testing from others, but not other operating systems (Windows, MacOS) nor any other init systems or installation setups.\n\n## Install\n\nListed below are the commands that can get wirestat set-up as a Systemd service on a modern amd64 linux system.\nCommands that would typically require root permissions are prefixed with `sudo`.\n\n```bash\n# Download latest release binary\ncurl https://github.com/ssddanbrown/wirestat/releases/latest/download/wirestat_linux_amd64 -Lo wirestat\n\n# Make binary executable \u0026 move binary to /usr/local/bin\nchmod +x wirestat\nsudo mv wirestat /usr/local/bin/wirestat\n\n# Create your rules file\nsudo mkdir /etc/wirestat\nsudo touch /etc/wirestat/rules.txt\n\n# Install as a systemd service\nwirestat systemd | sudo tee /etc/systemd/system/wirestat.service\nsudo systemctl enable wirestat\nsudo systemctl start wirestat\n```\n\nAfter these commands have been ran you should be able to access the wirestat output at `http://\u003cmachine_ip\u003e:8930`.\nYou will need to ensure that the wirestat port (8930 by default) is open for any required access.\nYou can check the wirestat service status using `sudo systemctl status wirestat`.\n\n## Update\n\nAssuming the above steps have been used for install, updating simply requires downloading and replacing the wirestat binary: \n\n```bash\n# Replace binary \u0026 restart systemd service\nsudo curl https://github.com/ssddanbrown/wirestat/releases/latest/download/wirestat_linux_amd64 -Lo /usr/local/bin/wirestat\nsudo chmod +x /usr/local/bin/wirestat\nsudo systemctl restart wirestat\n```\n\n## Uninstall\n\nAssuming the above steps have been used for install, you can pretty much do the reverse for uninstall:\n\n```bash\n# Stop and remove systemd service\nsudo systemctl stop wirestat\nsudo systemctl disable wirestat\nsudo rm /etc/systemd/system/wirestat.service\n\n# Delete rules\nsudo rm -r /etc/wirestat\n\n# Delete binary\nsudo rm /usr/local/bin/wirestat\n```\n\n## Defining Rules\n\nRules are defined in a plaintext file. By default wirestat will look for a `/etc/wirestat/rules.txt` file. See \"Options\" below for details on using a custom path.\n\nThe rules file should contain one rule per line, with each rule following this format:\n\n```\n\u003cmetric\u003e \u003coperator\u003e \u003cvalue\u003e : \u003crule name/label\u003e\n```\n\nWhere:\n\n- **metric**: Is the full property name of the metric you want to check against.\n- **operator**: One of: `\u003e`, `\u003c`, `=`, `!=`, `\u003c=`, `\u003e=`.\n- **value**: The numeric value you want compare the metric against.\n- **rule name/label**: A unique human friendly label to describe the rule.\n\nBlanks lines, and lines starting with a `#`, will be ignored.\n\nColons (`:`) can be escaped in strings with backslash (`\\\\`).\n\n**The rule should be true in the scenario you want to alert upon.**\n\n#### Rule File Example\n\n```txt\ncpu.all_active_percent \u003e= 50 : CPU utilization over 50%\nmemory.used_percent \u003e 80 : Memory usage over 80%\nfilesystem./dev/nvme0n1p3.used_percent \u003e 90 : Main disk is almost full\n\n# Barry advised we need to reboot this machine every 30 days\nuptime.days \u003e= 30 : System has been up for over 30 days\n```\n\n#### Applying Rule Changes\n\nRules are read by wirestat upon start-up. Simply restart your wirestat process to re-read the rule file (Commonly `systemctl restart wirestat`).\n\n## Alerts\n\nWhen a rule passes, its name will be added to the `alerts` output in the JSON response. When any alerts are present in this output, the JSON response will be served with a non-2xx (Typically 500) HTTP response code.\n\nUpon rules, internal issues may also show up in alerts. For example, invalidly defined rules may be advised of within the alerts output.\n\n## Metrics\n\nMetrics are polled in the background at ~5 second intervals. A `metrics_updated_at` property in the response reflects the last update time for this polling.\n\nAll metrics are reflected as an unsigned int64 value. Any metric that represents a percentage value is specifically labelled as such.\n\n#### CPU\n\nAll metrics are shown as percentages. Activity it taken from a 1 second sample from `/proc/stat`. Metrics will be shown for each thread upon a value for all threads.\n\n#### Filesystems\n\nThese metrics are take from parsing the command `df -P -B MB`. \nAll filesystems from this output will be reflected.\nNon-percentage values shown are in MegaBytes.\n\n#### Memory\n\nNon-percentage values shown are in MegaBytes.\n\n### Uptime\n\nUptime is shown broken down into a series of units. The lesser units are not the total amount of time passed for that type, but instead provide precision to the greater units. For example, `uptime.seconds` will not go above 59, it only shows the number of seconds since the last counted minute.\n\n## Options \u0026 Arguments\n\nwirestat can be provided some command line options. If it's setup as a Systemd service as above, you'd need to edit the command line options within the `ExecStart` line of your `/etc/systemd/system/wirestat.service` file.\n\n#### `-port`\n\nThe port to use to run the wirestat server on. Defaults to `8930`. Should be a port that's not used by any other service.\n\n```bash\n# Example of using wirestat on port 9090\nwirestat -port 9090\n```\n\n#### `-rules`\n\nThe path to the rules file to read. Defaults to `/etc/wirestat/rules.txt`.\n\n```bash\n# Example of using a custom rules file location\nwirestat -rules /home/barry/wirestat-rules.txt\n```\n\n#### `-accesskey`\n\nDefine a key string to be required to access the JSON output, as a very basic form of authorization.\n\n```bash\n# Example of setting a custom access key\nwirestat -accesskey \"hunter2\"\n```\n\nWhen this option is set you'll need to provide this key value, when accessing the JSON data, as either:\n\n- A `key` query parameter value in the URL.\n- A `X-Access-Key` header value.\n\n#### `systemd`\n\nThis argument will tell wirestat to print systemd configuration to stdout, instead of running the application as normal. Other options can be passed with this argument, and those options will be used within the command output.\n\n```bash\nwirestat -port 9090 -rules /root/rules.txt systemd\n```\n\n## Possible Issues\n\n##### SELinux preventing run via Systemd\n\nYou may need to reset the SELinux security context of the `/usr/local/bin/wirestat` binary after moving on systems with SELinux:\n\n```bash\nrestorecon /usr/local/bin/wirestat\n```\n\n## Low Maintenance Project\n\nThis is a low maintenance project. The scope of features and support are purposefully kept narrow for my purposes to ensure longer term maintenance is viable. I'm not looking to grow this into a bigger project at all.\n\nIssues and PRs raised for bugs are perfectly fine assuming they don't significantly increase the scope of the project. Please don't open PRs for new features that expand the scope.\n\n## Attribution\n\nThe following great projects are directly used within this project:\n\n- [goprocinfo](https://github.com/c9s/goprocinfo) - MIT Licensed\n- [testify](github.com/stretchr/testify) - MIT Licensed","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssddanbrown%2Fwirestat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fssddanbrown%2Fwirestat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssddanbrown%2Fwirestat/lists"}