Merge pull request #3454 from rda0/ntpd-documentation

Update documentation for ntpd

5 files changed, 141 insertions, 13 deletions

diff --git a/conf.d/python.d.conf b/conf.d/python.d.conf
index b250385ae0..bb57738bb0 100644
--- a/conf.d/python.d.conf
+++ b/conf.d/python.d.conf
@@ -56,6 +56,7 @@ go_expvar: no
 # nginx: yes
 # nginx_plus: yes
 # nsd: yes
+# ntpd: yes
 
 # nginx_log has been replaced by web_log
 nginx_log: no
diff --git a/conf.d/python.d/ntpd.conf b/conf.d/python.d/ntpd.conf
index fcb02f9eb8..7adc4074b4 100644
--- a/conf.d/python.d/ntpd.conf
+++ b/conf.d/python.d/ntpd.conf
@@ -58,7 +58,10 @@
 #
 # host: 'localhost'       # the host to query
 # port: '123'             # the UDP port where `ntpd` listens
-# show_peers: no          # use `yes` to show peer charts
+# show_peers: no          # use `yes` to show peer charts. enabling this
+#                         # option is recommended only for debugging, as
+#                         # it could possibly imply memory leaks if the
+#                         # peers change frequently.
 # peer_filter: '127\..*'  # regex to exclude peers
 #                         # by default local peers are hidden
 #                         # use `''` to show all peers.
@@ -68,3 +71,21 @@
 # ----------------------------------------------------------------------
 # AUTO-DETECTION JOBS
 # only one of them will run (they have the same name)
+
+localhost:
+  name: 'local'
+  host: 'localhost'
+  port: '123'
+  show_peers: no
+
+localhost_ipv4:
+  name: 'local'
+  host: '127.0.0.1'
+  port: '123'
+  show_peers: no
+
+localhost_ipv6:
+  name: 'local'
+  host: '::1'
+  port: '123'
+  show_peers: no
diff --git a/python.d/README.md b/python.d/README.md
index 5df1ec726f..b67e56acee 100644
--- a/python.d/README.md
+++ b/python.d/README.md
@@ -1543,10 +1543,10 @@ Configuration is not needed.
 
 # ntpd
 
-Module monitors the system variables of the local `ntpd` daemon (optional incl. variables of the polled peers) using the NTP Control Message Protocol via UDP socket, similar to `ntpq`.
+Module monitors the system variables of the local `ntpd` daemon (optional incl. variables of the polled peers) using the NTP Control Message Protocol via UDP socket, similar to `ntpq`, the [standard NTP query program](http://doc.ntp.org/current-stable/ntpq.html).
 
 **Requirements:**
- * Version of `ntpd` must be 2.0+
+ * Version: `NTPv4`
  * Local interrogation allowed in `/etc/ntp.conf` (default):
 
 ```
@@ -1591,12 +1591,15 @@ update_every: 10
 host: 'localhost'
 port: '123'
 show_peers: yes
+# hide peers with source address in ranges 127.0.0.0/8 and 192.168.0.0/16
 peer_filter: '(127\..*)|(192\.168\..*)'
+# check for new/changed peers every 60 updates
+peer_rescan: 60
 ```
 
 Sample (multiple jobs):
 
-Note: `ntp.conf` on host `otherhost` must be configured to allow queries from our local host by including a line like `restrict <IP> nomodify notrap nopeer`.
+Note: `ntp.conf` on the host `otherhost` must be configured to allow queries from our local host by including a line like `restrict <IP> nomodify notrap nopeer`.
 
 ```yaml
 local:
@@ -1606,7 +1609,7 @@ otherhost:
     host: 'otherhost'
 ```
 
-If no configuration is given, module will attempt to connect to `ntpd` on `::1:123` or `127.0.0.1:123` and show charts for the systemvars. Use `show_peers: yes` to also show the charts for configured peers. Local peers (127.*) are hidden by default, use `peer_filter: ''` to show all.
+If no configuration is given, module will attempt to connect to `ntpd` on `::1:123` or `127.0.0.1:123` and show charts for the systemvars. Use `show_peers: yes` to also show the charts for configured peers. Local peers in the range `127.0.0.0/8` are hidden by default, use `peer_filter: ''` to show all peers.
 
 ---
 
diff --git a/python.d/ntpd.chart.py b/python.d/ntpd.chart.py
index a2c5ad75d9..05209da871 100644
--- a/python.d/ntpd.chart.py
+++ b/python.d/ntpd.chart.py
@@ -86,7 +86,7 @@ CHARTS = {
             ['rootdisp', 'dispersion', 'absolute', 1, PRECISION]
         ]},
     'sys_stratum': {
-        'options': [None, 'Stratum (1-15)', '1', 'system', 'ntpd.sys_stratum', 'line'],
+        'options': [None, 'Stratum (1-15)', 'stratum', 'system', 'ntpd.sys_stratum', 'line'],
         'lines': [
             ['stratum', 'stratum', 'absolute', 1, PRECISION]
         ]},
@@ -135,15 +135,15 @@ PEER_CHARTS = {
         'lines': [
         ]},
     'peer_stratum': {
-        'options': [None, 'Stratum (1-15)', '1', 'peers', 'ntpd.peer_stratum', 'line'],
+        'options': [None, 'Stratum (1-15)', 'stratum', 'peers', 'ntpd.peer_stratum', 'line'],
         'lines': [
         ]},
     'peer_hmode': {
-        'options': [None, 'Host mode (1-6)', '1', 'peers', 'ntpd.peer_hmode', 'line'],
+        'options': [None, 'Host mode (1-6)', 'hmode', 'peers', 'ntpd.peer_hmode', 'line'],
         'lines': [
         ]},
     'peer_pmode': {
-        'options': [None, 'Peer mode (1-5)', '1', 'peers', 'ntpd.peer_pmode', 'line'],
+        'options': [None, 'Peer mode (1-5)', 'pmode', 'peers', 'ntpd.peer_pmode', 'line'],
         'lines': [
         ]},
     'peer_hpoll': {
@@ -225,7 +225,6 @@ class Service(SocketService):
         SocketService.__init__(self, configuration=configuration, name=name)
         self.order = list(ORDER)
         self.definitions = dict(CHARTS)
-        self.definitions.update(PEER_CHARTS)
 
         self.port = 'ntp'
         self.dgram_socket = True
@@ -236,6 +235,9 @@ class Service(SocketService):
         self.show_peers = self.configuration.get('show_peers', False)
         self.peer_rescan = self.configuration.get('peer_rescan', 60)
 
+        if self.show_peers:
+            self.definitions.update(PEER_CHARTS)
+
     def check(self):
         """
         Checks if we can get valid systemvars.
@@ -341,6 +343,11 @@ class Service(SocketService):
             srcadr = srcadr.group(2)
             if self.peer_filter.search(srcadr):
                 continue
+            stratum = re.search(r'(stratum)=([^,]+)', raw_peer_data)
+            if not stratum:
+                continue
+            if int(stratum.group(2)) > 15:
+                continue
 
             new_peer = Peer(idx=peer_id, name=srcadr)
             new_peers.append(new_peer)
diff --git a/web/dashboard_info.js b/web/dashboard_info.js
index e68736e74a..e2864b0a81 100644
--- a/web/dashboard_info.js
+++ b/web/dashboard_info.js
@@ -358,7 +358,7 @@ netdataDashboard.menu = {
     'ntpd': {
         title: 'ntpd',
         icon: '<i class="fas fa-clock"></i>',
-        info: 'Provides statistics for the internal variables of the Network Time Protocol daemon <b><a href="http://www.ntp.org/">ntpd</a></b> including the configured peers.'
+        info: 'Provides statistics for the internal variables of the Network Time Protocol daemon <b><a href="http://www.ntp.org/">ntpd</a></b> and optional including the configured peers (if enabled in the module configuration). The module presents the performance metrics as shown by <b><a href="http://doc.ntp.org/current-stable/ntpq.html">ntpq</a></b> (the standard NTP query program) using NTP mode 6 UDP packets to communicate with the NTP server.'
     }
 };
 
@@ -513,12 +513,12 @@ netdataDashboard.submenu = {
 
     'ntpd.system': {
         title: 'system',
-        info: 'Statistics of the internal system variables as shown by <a href="http://doc.ntp.org/current-stable/ntpq.html">ntpq</a> (standard NTP query program).'
+        info: 'Statistics of the system variables as shown by the readlist billboard <code>ntpq -c rl</code>. System variables are assigned an association ID of zero and can also be shown in the readvar billboard <code>ntpq -c "rv 0"</code>. These variables are used in the <a href="http://doc.ntp.org/current-stable/discipline.html">Clock Discipline Algorithm</a>, to calculate the lowest and most stable offset.'
     },
 
     'ntpd.peers': {
         title: 'peers',
-        info: 'Statistics of the peer variables for each peer as shown by <a href="http://doc.ntp.org/current-stable/ntpq.html">ntpq</a> (standard NTP query program).'
+        info: 'Statistics of the peer variables for each peer configured in <code>/etc/ntp.conf</code> as shown by the readvar billboard <code>ntpq -c "rv &lt;association&gt;"</code>, while each peer is assigned a nonzero association ID as shown by <code>ntpq -c "apeers"</code>. The module periodically scans for new/changed peers (default: every 60s). <b>ntpd</b> selects the best possible peer from the available peers to synchronize the clock. A minimum of at least 3 peers is required to properly identify the best possible peer.'
     }
 };
 
@@ -1962,6 +1962,102 @@ netdataDashboard.context = {
     'rabbitmq.disk_space': {
         info: 'Total amount of disk space consumed by the message store(s).  See <code><a href="https://www.rabbitmq.com/production-checklist.html#resource-limits-disk-space" target=_"blank">Disk Space Limits</a></code> for further details.',
         colors: NETDATA.colors[3]
+    },
+
+    // ------------------------------------------------------------------------
+    // ntpd
+
+    'ntpd.sys_offset': {
+        info: 'For hosts without any time critical services an offset of &lt; 100 ms should be acceptable even with high network latencies. For hosts with time critical services an offset of about 0.01 ms or less can be achieved by using peers with low delays and configuring optimal <b>poll exponent</b> values.',
+        colors: NETDATA.colors[4]
+    },
+
+    'ntpd.sys_jitter': {
+        info: 'The jitter statistics are exponentially-weighted RMS averages. The system jitter is defined in the NTPv4 specification; the clock jitter statistic is computed by the clock discipline module.'
+    },
+
+    'ntpd.sys_frequency': {
+        info: 'The frequency offset is shown in ppm (parts per million) relative to the frequency of the system. The frequency correction needed for the clock can vary significantly between boots and also due to external influences like temperature or radiation.',
+        colors: NETDATA.colors[2],
+        height: 0.6
+    },
+
+    'ntpd.sys_wander': {
+        info: 'The wander statistics are exponentially-weighted RMS averages.',
+        colors: NETDATA.colors[3],
+        height: 0.6
+    },
+
+    'ntpd.sys_rootdelay': {
+        info: 'The rootdelay is the round-trip delay to the primary reference clock, similar to the delay shown by the <code>ping</code> command. A lower delay should result in a lower clock offset.',
+        colors: NETDATA.colors[1]
+    },
+
+    'ntpd.sys_stratum': {
+        info: 'The distance in "hops" to the primary reference clock',
+        colors: NETDATA.colors[5],
+        height: 0.3
+    },
+
+    'ntpd.sys_tc': {
+        info: 'Time constants and poll intervals are expressed as exponents of 2. The default poll exponent of 6 corresponds to a poll interval of 64 s. For typical Internet paths, the optimum poll interval is about 64 s. For fast LANs with modern computers, a poll exponent of 4 (16 s) is appropriate. The <a href="http://doc.ntp.org/current-stable/poll.html">poll process</a> sends NTP packets at intervals determined by the clock discipline algorithm.',
+        height: 0.5
+    },
+
+    'ntpd.sys_precision': {
+        colors: NETDATA.colors[6],
+        height: 0.2
+    },
+
+    'ntpd.peer_offset': {
+        info: 'The offset of the peer clock relative to the system clock in milliseconds. Smaller values here weight peers more heavily for selection after the initial synchronization of the local clock. For a system providing time service to other systems, these should be as low as possible.'
+    },
+
+    'ntpd.peer_delay': {
+        info: 'The round-trip time (RTT) for communication with the peer, similar to the delay shown by the <code>ping</code> command. Not as critical as either the offset or jitter, but still factored into the selection algorithm (because as a general rule, lower delay means more accurate time). In most cases, it should be below 100ms.'
+    },
+
+    'ntpd.peer_dispersion': {
+        info: 'This is a measure of the estimated error between the peer and the local system. Lower values here are better.'
+    },
+
+    'ntpd.peer_jitter': {
+        info: 'This is essentially a remote estimate of the peer\'s <code>system_jitter</code> value. Lower values here weight highly in favor of peer selection, and this is a good indicator of overall quality of a given time server (good servers will have values not exceeding single digit milliseconds here, with high quality stratum one servers regularly having sub-millisecond jitter).'
+    },
+
+    'ntpd.peer_xleave': {
+        info: 'This variable is used in interleaved mode (used only in NTP symmetric and broadcast modes). See <a href="http://doc.ntp.org/current-stable/xleave.html">NTP Interleaved Modes</a>.'
+    },
+
+    'ntpd.peer_rootdelay': {
+        info: 'For a stratum 1 server, this is the access latency for the reference clock. For lower stratum servers, it is the sum of the <code>peer_delay</code> and <code>peer_rootdelay</code> for the system they are syncing off of. Similarly to <code>peer_delay</code>, lower values here are technically better, but have limited influence in peer selection.'
+    },
+
+    'ntpd.peer_rootdisp': {
+        info: 'Is the same as <code>peer_rootdelay</code>, but measures accumulated <code>peer_dispersion</code> instead of accumulated <code>peer_delay</code>.'
+    },
+
+    'ntpd.peer_hmode': {
+        info: 'The <code>peer_hmode</code> and <code>peer_pmode</code> variables give info about what mode the packets being sent to and received from a given peer are. Mode 1 is symmetric active (both the local system and the remote peer have each other declared as peers in <code>/etc/ntp.conf</code>), Mode 2 is symmetric passive (only one side has the other declared as a peer), Mode 3 is client, Mode 4 is server, and Mode 5 is broadcast (also used for multicast and manycast operation).',
+        height: 0.2
+    },
+
+    'ntpd.peer_pmode': {
+        height: 0.2
+    },
+
+    'ntpd.peer_hpoll': {
+        info: 'The <code>peer_hpoll</code> and <code>peer_ppoll</code> variables are log2 representations of the polling interval in seconds.',
+        height: 0.5
+    },
+
+    'ntpd.peer_ppoll': {
+        height: 0.5
+    },
+
+    'ntpd.peer_precision': {
+        height: 0.2
     }
+
     // ------------------------------------------------------------------------
 };