{"id":18501713,"url":"https://github.com/paulgear/ntpmon","last_synced_at":"2025-04-09T01:32:22.472Z","repository":{"id":12781736,"uuid":"59459741","full_name":"paulgear/ntpmon","owner":"paulgear","description":"Monitor for essential NTP metrics","archived":false,"fork":false,"pushed_at":"2024-05-09T22:48:33.000Z","size":1282,"stargazers_count":44,"open_issues_count":2,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-23T20:37:01.358Z","etag":null,"topics":["chrony","collectd-plugin","monitoring","ntp","prometheus","python3","telegraf"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulgear.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-23T07:04:02.000Z","updated_at":"2025-03-13T06:50:18.000Z","dependencies_parsed_at":"2022-08-07T07:00:43.748Z","dependency_job_id":"687f27ff-427e-4775-833d-1cde507c7d29","html_url":"https://github.com/paulgear/ntpmon","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulgear%2Fntpmon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulgear%2Fntpmon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulgear%2Fntpmon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulgear%2Fntpmon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulgear","download_url":"https://codeload.github.com/paulgear/ntpmon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247956996,"owners_count":21024630,"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":["chrony","collectd-plugin","monitoring","ntp","prometheus","python3","telegraf"],"created_at":"2024-11-06T13:54:39.302Z","updated_at":"2025-04-09T01:32:21.355Z","avatar_url":"https://github.com/paulgear.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NTPmon\n\n## Introduction\n\nNTPmon is a program which is designed to report on essential health metrics for\nNTP.  It provides a Nagios check which can be used with many alerting systems,\nincluding support for Nagios performance data.  NTPmon can also run as a daemon\nfor sending metrics to collectd, prometheus, or telegraf.  It supports both\n`ntpd` and `chronyd`.\n\nNTPmon is designed to encourage the use of robust NTP configurations.  The\ndefaults for what is considered healthy and non-healthy are roughly based on\n[RFC8633: NTP Best Current\nPractices](https://datatracker.ietf.org/doc/html/rfc8633).\n\n## Copyright\n\nCopyright (c) 2015-2024 Paul D. Gear \u003chttps://libertysys.com.au/\u003e\n\n## License\n\nThis program is free software: you can redistribute it and/or modify it under\nthe terms of the GNU Affero General Public License as published by the Free\nSoftware Foundation, either version 3 of the License, or (at your option) any\nlater version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License along\nwith this program.  If not, see \u003chttps://www.gnu.org/licenses/agpl.html\u003e.\n\n## Gallery\n\nHere are some graphs produced with data gathered by NTPmon using telegraf,\nInfluxDB, and Grafana.\n\nA system offset graph:\n\n![Graph of system offset](doc/offset.png)\n\nA system offset histogram:\n\n![Histogram of system offset](doc/offset-histogram.png)\n\nA root dispersion graph:\n\n![Graph of root dispersion](doc/root-dispersion.png)\n\nA frequency error graph showing variation based on temperature due to time of day:\n\n![Histogram of frequency error](doc/frequency.png)\n\nOr you could try these interactive Grafana dashboard snapshots:\n- https://snapshots.raintank.io/dashboard/snapshot/QV6YTE7nuInMuThGEBtViPLWNoAZqTYs\n- https://snapshots.raintank.io/dashboard/snapshot/V8lcRJEY1jhHe1h8EqQSEalkzEW9WG0O\n- https://snapshots.raintank.io/dashboard/snapshot/xHdgapqImIxKOH36x9dk2rkA6UjPYrwg\n- https://snapshots.raintank.io/dashboard/snapshot/FrJ0HQJ6lpBtfjezDHwbwKVauChd9TMN\n- https://snapshots.raintank.io/dashboard/snapshot/jQUiLFkHKNKJJSJZLz6ZiYpaKA3X2EH4\n\nYou can find more context for these dashboards in the following blog posts:\n\n- https://www.libertysys.com.au/2024/04/aws-microsecond-accurate-time-first-look/\n- https://www.libertysys.com.au/2024/04/tlntc-time-infrastructure/\n- https://www.libertysys.com.au/2024/04/vm-timekeeping-using-the-ptp-hardware-clock-on-kvm/\n\n## Installation\n\nOn Ubuntu (and possibly other Debian derivatives) NTPmon and its prerequisites\ncan be installed from [its\nPPA](https://launchpad.net/~paulgear/+archive/ubuntu/ntpmon/) using:\n\n    sudo add-apt-repository ppa:paulgear/ntpmon\n    sudo apt install chrony ntpmon\n\n`chrony` is the preferred NTP server on Ubuntu; you can also use `ntp` or\n`ntpsec` from the universe pool, although the are not guaranteed to receive\nsecurity updates unless you use Ubuntu Pro.\n\nIf you wish to use something other than the prometheus exporter by default, you\nmust edit `/etc/default/ntpmon` to configure the command-line options.  Run\n`/opt/ntpmon/bin/ntpmon --help` for details of all available options.\n\n## Prerequisites\n\nNTPmon is written in python, and requires python 3.8 or later.  It uses modules\nfrom the standard python library, and also requires the `psutil` library, which\nis available from pypi or your operating system repositories. It requires `ntpq`\nor `chronyc` to retrieve metrics from the running NTP daemon. If you intend to\nrun the prometheus exporter, the [prometheus python\nclient](https://pypi.org/project/prometheus-client/) is also required.\n\nOn Ubuntu (and probably other Debian-based Linux distributions), you can install\nall the prerequisites by running:\n\n    sudo apt-get install chrony python3-prometheus-client python3-psutil\n    # or substitute ntp for the traditional NTP server\n\n## Usage\n\nTo run NTPmon directly from source after manually installing the prerequisites:\n\n    cd /opt\n    git clone https://github.com/paulgear/ntpmon\n    cd ntpmon\n    ./src/ntpmon.py --help\n\n## Metrics\n\nNTPmon alerts on the following metrics of the local NTP server:\n\n### Summary metrics\n\n#### sync\n\nDoes NTP have a sync peer?  If not, return CRITICAL, otherwise return OK.\n\n#### peers\n\nAre there more than the minimum number of peers active?  The NTP algorithms\nrequire a minimum of 3 peers for accurate clock management; to allow for failure\nor maintenance of one peer at all times, NTPmon returns OK for [4 or more\nconfigured peers](https://datatracker.ietf.org/doc/html/rfc8633#section-3.2),\nCRITICAL for 1 or 0, and WARNING for 2-3.\n\n#### reach\n\nAre the configured peers reliably reachable on the network?  Return CRITICAL for\nless than 50% total reachability of all configured peers; return OK for greater\nthan 75% total reachability of all configured peers.\n\n#### offset\n\nIs the clock offset from its sync peer (or other peers, if the sync peer is not\navailable) acceptable?  Return CRITICAL for 50 milliseconds or more average\ndifference, WARNING for 10 ms or more average difference, and OK for anything\nless.\n\n### System metrics\n\nIn addition, NTPmon retrieves the following metrics directly from the local NTP\nserver (using `ntpq -nc readvar` or `chronyc -c tracking`):\n\n- offset (as `sysoffset`, to distinguish it from `offset`)\n- sys_jitter (as `sysjitter`, for grouping with `sysoffset`)\n- frequency\n- stratum\n- rootdelay\n- rootdisp\n\nSee the [NTP documentation](http://doc.ntp.org/current-stable/ntpq.html#system)\nfor the meaning of these metrics.\n\n### Peer metrics\n\nCounts of each peer type are emitted under the `ntpmon_peers` metric.  The\nrecognised peer types are `pps`, `sync`, `invalid`, `false`, `excess`, `backup`,\n`outlier`, `survivor`, and `unknown`.  (Under normal circumstances, `unknown`\nwill never appear - its presence indicates a bug in NTPmon.)  Note that `sync`\nalso includes the `pps` peer (if any), and `survivor` also includes the `sync`\npeer (if any), so they are not strictly mutually exclusive.  There should be no\noverlap in any of the other types.\n\nIf your `chronyd` or `ntpd` is configured to store peer (source) statistics,\nthese will be collected as they appear in the relevant log files\n(`/var/log/chrony/measurements.log` and `/var/log/ntpstats/peerstats`,\nrespectively, by default) and emitted under the `ntpmon_peer` (singluar) metric,\nin addition to all the above-mentioned metrics.  Use the `--logfile` command\nline option to monitor a different file if your distribution uses different\nlocations.  NTPmon will silently ignore any issues relating to these files in\norder to continue running, so if you don't notice metrics coming out when you\nexpect them, check permissions on the files and compare their contents to the\ndocumented formats.  Please submit a bug report if you encounter persistent\nissues with this.\n\n`Collectd` doesn't have a really great way to support these individual peer\nmetrics, so each peer is considered to be a `collectd` \"host\".  This feature\nshould be considered experimental for `collectd`, and subject to change or\ndeprecation (input on this is welcome).\n\n## Prometheus exporter\n\nWhen run in prometheus mode, NTPmon uses the [prometheus python\nclient](https://pypi.python.org/pypi/prometheus_client) to expose metrics via\nthe HTTP server built into that library.  No security testing or validation has\nbeen performed on this library by the NTPmon author; users are suggested not to\nexpose it on untrusted networks, and are reminded that - as stated in the\nlicense terms - this software comes with no warranty.\n\n## Telegraf integration\n\nWhen run in telegraf mode, NTPmon requires the telegraf [socket\nlistener](https://docs.influxdata.com/telegraf/v1/plugins/#input-socket_listener)\ninput plugin to be enabled.  Use the `--connect` command-line option if you\nconfigure this to listen on a host and/or port other than the default\n(127.0.0.1:8094).\n\n## Startup delay\n\nBy default, until the NTP server has been running for 512 seconds (the minimum\ntime for 8 polls at 64-second intervals), `check_ntpmon` will return OK (zero\nreturn code). This is to prevent false positives on startup or for short-lived\nVMs.  To ignore this safety precaution, use `--run-time` with a low number\n(e.g. 1 sec).\n\n## Roadmap\n\n### Python version\n\nThe current minimum python version targeted is 3.8.  This version [reaches end\nof life in October 2024](https://www.python.org/downloads/) and will be\ndeprecated in NTPmon sometime between [the release of Ubuntu\n24.04](https://discourse.ubuntu.com/t/noble-numbat-release-schedule/35649)\n(\"Noble Numbat\") in April 2024 and python 3.8's EOL date.\n\n### Output integrations\n\nTelegraf is the preferred output integration for NTPmon (over collectd and\nprometheus), due to its higher resolution timestamps, and measuring the\ntimestamp at the source which generated it rather than the scraping host.  The\nother integrations (first collectd, then Nagios, then prometheus) may eventually\ngo away if they are not widely used.  Please let me know (via an\n[issue](https://github.com/paulgear/ntpmon/issues)) if you have strong feelings\nabout this.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulgear%2Fntpmon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulgear%2Fntpmon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulgear%2Fntpmon/lists"}