Input plugin for running ntp queries

CHANGELOG.md

@@ -17,6 +17,7 @@
 - [#811](https:/influxdata/telegraf/pull/811): Add processes plugin for classifying total procs on system. Thanks @titilambert!
 - [#235](https:/influxdata/telegraf/issues/235): Add number of users to the `system` input plugin.
 - [#826](https:/influxdata/telegraf/pull/826): "kernel" linux plugin for /proc/stat metrics (context switches, interrupts, etc.)
+- [#847](https:/influxdata/telegraf/pull/847): `ntpq`: Input plugin for running ntp query executable and gathering metrics.
 
 ### Bugfixes
 - [#748](https:/influxdata/telegraf/issues/748): Fix sensor plugin split on ":"

plugins/inputs/EXAMPLE_README.md

@@ -30,8 +30,6 @@ The example plugin gathers metrics about example things
 
 ### Example Output:
 
-Give an example `-test` output here
-
 ```
 $ ./telegraf -config telegraf.conf -input-filter example -test
 measurement1,tag1=foo,tag2=bar field1=1i,field2=2.1 1453831884664956455

plugins/inputs/all/all.go

@@ -29,6 +29,7 @@ import (
  _ "github.com/influxdata/telegraf/plugins/inputs/net_response"
  _ "github.com/influxdata/telegraf/plugins/inputs/nginx"
  _ "github.com/influxdata/telegraf/plugins/inputs/nsq"
+ _ "github.com/influxdata/telegraf/plugins/inputs/ntpq"
  _ "github.com/influxdata/telegraf/plugins/inputs/passenger"
  _ "github.com/influxdata/telegraf/plugins/inputs/phpfpm"
  _ "github.com/influxdata/telegraf/plugins/inputs/ping"

plugins/inputs/ntpq/README.md

@@ -0,0 +1,60 @@
+# ntpq Input Plugin
+
+Get standard NTP query metrics, requires ntpq executable.
+
+Below is the documentation of the various headers returned from the NTP query
+command when running `ntpq -p`.
+
+- remote – The remote peer or server being synced to. “LOCAL” is this local host
+(included in case there are no remote peers or servers available);
+- refid – Where or what the remote peer or server is itself synchronised to;
+- st (stratum) – The remote peer or server Stratum
+- t (type) – Type (u: unicast or manycast client, b: broadcast or multicast client,
+l: local reference clock, s: symmetric peer, A: manycast server,
+B: broadcast server, M: multicast server, see “Automatic Server Discovery“);
+- when – When last polled (seconds ago, “h” hours ago, or “d” days ago);
+- poll – Polling frequency: rfc5905 suggests this ranges in NTPv4 from 4 (16s)
+to 17 (36h) (log2 seconds), however observation suggests the actual displayed
+value is seconds for a much smaller range of 64 (26) to 1024 (210) seconds;
+- reach – An 8-bit left-shift shift register value recording polls (bit set =
+successful, bit reset = fail) displayed in octal;
+- delay – Round trip communication delay to the remote peer or server (milliseconds);
+- offset – Mean offset (phase) in the times reported between this local host and
+the remote peer or server (RMS, milliseconds);
+- jitter – Mean deviation (jitter) in the time reported for that remote peer or
+server (RMS of difference of multiple time samples, milliseconds);
+
+### Configuration:
+
+```toml
+# Get standard NTP query metrics, requires ntpq executable
+[[inputs.ntpq]]
+ ## If false, set the -n ntpq flag. Can reduce metric gather times.
+ dns_lookup = true
+```
+
+### Measurements & Fields:
+
+- ntpq
+ - delay (float, milliseconds)
+ - jitter (float, milliseconds)
+ - offset (float, milliseconds)
+ - poll (int, seconds)
+ - reach (int)
+ - when (int, seconds)
+
+### Tags:
+
+- All measurements have the following tags:
+ - refid
+ - remote
+ - type
+ - stratum
+
+### Example Output:
+
+```
+$ telegraf -config ~/ws/telegraf.conf -input-filter ntpq -test
+* Plugin: ntpq, Collection 1
+> ntpq,refid=.GPSs.,remote=*time.apple.com,stratum=1,type=u delay=91.797,jitter=3.735,offset=12.841,poll=64i,reach=377i,when=35i 1457960478909556134
+```

plugins/inputs/ntpq/ntpq.go

@@ -0,0 +1,202 @@
+// +build !windows
+
+package ntpq
+
+import (
+ "bufio"
+ "bytes"
+ "log"
+ "os/exec"
+ "strconv"
+ "strings"
+
+ "github.com/influxdata/telegraf"
+ "github.com/influxdata/telegraf/plugins/inputs"
+)
+
+// Mapping of ntpq header names to tag keys
+var tagHeaders map[string]string = map[string]string{
+ "remote": "remote",
+ "refid": "refid",
+ "st": "stratum",
+ "t": "type",
+}
+
+// Mapping of the ntpq tag key to the index in the command output
+var tagI map[string]int = map[string]int{
+ "remote": -1,
+ "refid": -1,
+ "stratum": -1,
+ "type": -1,
+}
+
+// Mapping of float metrics to their index in the command output
+var floatI map[string]int = map[string]int{
+ "delay": -1,
+ "offset": -1,
+ "jitter": -1,
+}
+
+// Mapping of int metrics to their index in the command output
+var intI map[string]int = map[string]int{
+ "when": -1,
+ "poll": -1,
+ "reach": -1,
+}
+
+type NTPQ struct {
+ runQ func() ([]byte, error)
+
+ DNSLookup bool `toml:"dns_lookup"`
+}
+
+func (n *NTPQ) Description() string {
+ return "Get standard NTP query metrics, requires ntpq executable."
+}
+
+func (n *NTPQ) SampleConfig() string {
+ return `
+ ## If false, set the -n ntpq flag. Can reduce metric gather time.
+ dns_lookup = true
+`
+}
+
+func (n *NTPQ) Gather(acc telegraf.Accumulator) error {
+ out, err := n.runQ()
+ if err != nil {
+ return err
+ }
+
+ lineCounter := 0
+ scanner := bufio.NewScanner(bytes.NewReader(out))
+ for scanner.Scan() {
+ fields := strings.Fields(scanner.Text())
+ if len(fields) < 2 {
+ continue
+ }
+
+ // If lineCounter == 0, then this is the header line
+ if lineCounter == 0 {
+ for i, field := range fields {
+ // Check if field is a tag:
+ if tagKey, ok := tagHeaders[field]; ok {
+ tagI[tagKey] = i
+ continue
+ }
+
+ // check if field is a float metric:
+ if _, ok := floatI[field]; ok {
+ floatI[field] = i
+ continue
+ }
+
+ // check if field is an int metric:
+ if _, ok := intI[field]; ok {
+ intI[field] = i
+ continue
+ }
+ }
+ } else {
+ tags := make(map[string]string)
+ mFields := make(map[string]interface{})
+
+ // Get tags from output
+ for key, index := range tagI {
+ if index == -1 {
+ continue
+ }
+ tags[key] = fields[index]
+ }
+
+ // Get integer metrics from output
+ for key, index := range intI {
+ if index == -1 {
+ continue
+ }
+
+ if key == "when" {
+ when := fields[index]
+ switch {
+ case strings.HasSuffix(when, "h"):
+ m, err := strconv.Atoi(strings.TrimSuffix(fields[index], "h"))
+ if err != nil {
+ log.Printf("ERROR ntpq: parsing int: %s", fields[index])
+ continue
+ }
+ // seconds in an hour
+ mFields[key] = int64(m) * 360
+ continue
+ case strings.HasSuffix(when, "d"):
+ m, err := strconv.Atoi(strings.TrimSuffix(fields[index], "d"))
+ if err != nil {
+ log.Printf("ERROR ntpq: parsing int: %s", fields[index])
+ continue
+ }
+ // seconds in a day
+ mFields[key] = int64(m) * 86400
+ continue
+ case strings.HasSuffix(when, "m"):
+ m, err := strconv.Atoi(strings.TrimSuffix(fields[index], "m"))
+ if err != nil {
+ log.Printf("ERROR ntpq: parsing int: %s", fields[index])
+ continue
+ }
+ // seconds in a day
+ mFields[key] = int64(m) * 60
+ continue
+ }
+ }
+
+ m, err := strconv.Atoi(fields[index])
+ if err != nil {
+ log.Printf("ERROR ntpq: parsing int: %s", fields[index])
+ continue
+ }
+ mFields[key] = int64(m)
+ }
+
+ // get float metrics from output
+ for key, index := range floatI {
+ if index == -1 {
+ continue
+ }
+
+ m, err := strconv.ParseFloat(fields[index], 64)
+ if err != nil {
+ log.Printf("ERROR ntpq: parsing float: %s", fields[index])
+ continue
+ }
+ mFields[key] = m
+ }
+
+ acc.AddFields("ntpq", mFields, tags)
+ }
+
+ lineCounter++
+ }
+ return nil
+}
+
+func (n *NTPQ) runq() ([]byte, error) {
+ bin, err := exec.LookPath("ntpq")
+ if err != nil {
+ return nil, err
+ }
+
+ var cmd *exec.Cmd
+ if n.DNSLookup {
+ cmd = exec.Command(bin, "-p")
+ } else {
+ cmd = exec.Command(bin, "-p", "-n")
+ }
+
+ return cmd.Output()
+}
+
+func init() {
+ inputs.Add("ntpq", func() telegraf.Input {
+ n := &NTPQ{}
+ n.runQ = n.runq
+ return n
+ })
+}