feat(inputs.ntpq): Allow to specify `reach` output format (#11594)

plugins/inputs/ntpq/README.md

@@ -29,6 +29,10 @@ server (RMS of difference of multiple time samples, milliseconds);
 ```toml @sample.conf
 # Get standard NTP query metrics, requires ntpq executable.
 [[inputs.ntpq]]
+  ## Servers to query with ntpq.
+  ## If no server is given, the local machine is queried.
+  # servers = []
+
   ## If false, set the -n ntpq flag. Can reduce metric gather time.
   ## DEPRECATED since 1.24.0: add '-n' to 'options' instead to skip DNS lookup
   # dns_lookup = true
@@ -36,9 +40,14 @@ server (RMS of difference of multiple time samples, milliseconds);
   ## Options to pass to the ntpq command.
   # options = "-p"
 
-  ## Servers to query with ntpq.
+  ## Output format for the 'reach' field.
-  ## If no server is given, the local machine is queried.
+  ## Available values are
-  # servers = []
+  ##   octal   --  output as is in octal representation e.g. 377 (default)
+  ##   decimal --  convert value to decimal representation e.g. 371 -> 249
+  ##   count   --  count the number of bits in the value. This represents
+  ##               the number of successful reaches, e.g. 37 -> 5
+  ##   ratio   --  output the ratio of successful attempts e.g. 37 -> 5/8 = 0.625
+  # reach_format = "octal"
 ```
 
 You can pass arbitrary options accepted by the `ntpq` command using the

plugins/inputs/ntpq/ntpq.go

@@ -6,6 +6,7 @@ import (
 	"bytes"
 	_ "embed"
 	"fmt"
+	"math/bits"
 	"os/exec"
 	"regexp"
 	"strconv"
@@ -19,6 +20,7 @@ import (
 )
 
 // DO NOT REMOVE THE NEXT TWO LINES! This is required to embed the sampleConfig data.
+//
 //go:embed sample.conf
 var sampleConfig string
 
@@ -32,9 +34,12 @@ type elementType int64
 const (
 	None elementType = iota
 	Tag
-	FieldInt
 	FieldFloat
 	FieldDuration
+	FieldIntDecimal
+	FieldIntOctal
+	FieldIntRatio8
+	FieldIntBits
 )
 
 type column struct {
@@ -55,15 +60,16 @@ var fieldElements = map[string]elementType{
 	"delay":  FieldFloat,
 	"jitter": FieldFloat,
 	"offset": FieldFloat,
-	"reach":  FieldInt,
+	"reach":  FieldIntDecimal,
 	"poll":   FieldDuration,
 	"when":   FieldDuration,
 }
 
 type NTPQ struct {
-	DNSLookup bool     `toml:"dns_lookup" deprecated:"1.24.0;add '-n' to 'options' instead to skip DNS lookup"`
+	DNSLookup   bool     `toml:"dns_lookup" deprecated:"1.24.0;add '-n' to 'options' instead to skip DNS lookup"`
-	Options   string   `toml:"options"`
+	Options     string   `toml:"options"`
-	Servers   []string `toml:"servers"`
+	Servers     []string `toml:"servers"`
+	ReachFormat string   `toml:"reach_format"`
 
 	runQ func(string) ([]byte, error)
 }
@@ -104,6 +110,29 @@ func (n *NTPQ) Init() error {
 			return cmd.Output()
 		}
 	}
+
+	switch n.ReachFormat {
+	case "", "octal":
+		n.ReachFormat = "octal"
+		// Interpret the field as decimal integer returning
+		// the raw (octal) representation
+		fieldElements["reach"] = FieldIntDecimal
+	case "decimal":
+		// Interpret the field as octal integer returning
+		// decimal number representation
+		fieldElements["reach"] = FieldIntOctal
+	case "count":
+		// Interpret the field as bits set returning
+		// the number of bits set
+		fieldElements["reach"] = FieldIntBits
+	case "ratio":
+		// Interpret the field as ratio between the number of
+		// bits set and the maximum available bits set (8).
+		fieldElements["reach"] = FieldIntRatio8
+	default:
+		return fmt.Errorf("unknown 'reach_format' %q", n.ReachFormat)
+	}
+
 	return nil
 }
 
@@ -187,14 +216,6 @@ func (n *NTPQ) gatherServer(acc telegraf.Accumulator, server string) {
 				continue
 			case Tag:
 				tags[col.name] = raw
-			case FieldInt:
-				value, err := strconv.ParseInt(raw, 10, 64)
-				if err != nil {
-					msg := fmt.Sprintf("%sparsing %q (%v) as int failed", msgPrefix, col.name, raw)
-					acc.AddError(fmt.Errorf("%s: %w", msg, err))
-					continue
-				}
-				fields[col.name] = value
 			case FieldFloat:
 				value, err := strconv.ParseFloat(raw, 64)
 				if err != nil {
@@ -223,6 +244,34 @@ func (n *NTPQ) gatherServer(acc telegraf.Accumulator, server string) {
 					continue
 				}
 				fields[col.name] = value * factor
+			case FieldIntDecimal:
+				value, err := strconv.ParseInt(raw, 10, 64)
+				if err != nil {
+					acc.AddError(fmt.Errorf("parsing %q (%v) as int failed: %w", col.name, raw, err))
+					continue
+				}
+				fields[col.name] = value
+			case FieldIntOctal:
+				value, err := strconv.ParseInt(raw, 8, 64)
+				if err != nil {
+					acc.AddError(fmt.Errorf("parsing %q (%v) as int failed: %w", col.name, raw, err))
+					continue
+				}
+				fields[col.name] = value
+			case FieldIntBits:
+				value, err := strconv.ParseUint(raw, 8, 64)
+				if err != nil {
+					acc.AddError(fmt.Errorf("parsing %q (%v) as int failed: %w", col.name, raw, err))
+					continue
+				}
+				fields[col.name] = bits.OnesCount64(value)
+			case FieldIntRatio8:
+				value, err := strconv.ParseUint(raw, 8, 64)
+				if err != nil {
+					acc.AddError(fmt.Errorf("parsing %q (%v) as int failed: %w", col.name, raw, err))
+					continue
+				}
+				fields[col.name] = float64(bits.OnesCount64(value)) / float64(8)
 			}
 		}
 

plugins/inputs/ntpq/ntpq_test.go

@@ -18,6 +18,26 @@ import (
 	"github.com/influxdata/telegraf/testutil"
 )
 
+func TestInitInvalid(t *testing.T) {
+	tests := []struct {
+		name     string
+		plugin   *NTPQ
+		expected string
+	}{
+		{
+			name:     "invalid reach_format",
+			plugin:   &NTPQ{ReachFormat: "garbage"},
+			expected: `unknown 'reach_format' "garbage"`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			require.EqualError(t, tt.plugin.Init(), tt.expected)
+		})
+	}
+}
+
 func TestCases(t *testing.T) {
 	// Get all directories in testdata
 	folders, err := os.ReadDir("testcases")

plugins/inputs/ntpq/sample.conf

@@ -1,5 +1,9 @@
 # Get standard NTP query metrics, requires ntpq executable.
 [[inputs.ntpq]]
+  ## Servers to query with ntpq.
+  ## If no server is given, the local machine is queried.
+  # servers = []
+
   ## If false, set the -n ntpq flag. Can reduce metric gather time.
   ## DEPRECATED since 1.24.0: add '-n' to 'options' instead to skip DNS lookup
   # dns_lookup = true
@@ -7,6 +11,11 @@
   ## Options to pass to the ntpq command.
   # options = "-p"
 
-  ## Servers to query with ntpq.
+  ## Output format for the 'reach' field.
-  ## If no server is given, the local machine is queried.
+  ## Available values are
-  # servers = []
+  ##   octal   --  output as is in octal representation e.g. 377 (default)
+  ##   decimal --  convert value to decimal representation e.g. 371 -> 249
+  ##   count   --  count the number of bits in the value. This represents
+  ##               the number of successful reaches, e.g. 37 -> 5
+  ##   ratio   --  output the ratio of successful attempts e.g. 37 -> 5/8 = 0.625
+  # reach_format = "octal"

plugins/inputs/ntpq/testcases/single_reach_count/expected.out

@@ -0,0 +1 @@
+ntpq,remote=uschi5-ntp-002.,state_prefix=*,refid=10.177.80.46,stratum=2,type=u when=101i,poll=256i,reach=5i,delay=51.016,offset=233.010,jitter=17.462 0

plugins/inputs/ntpq/testcases/single_reach_count/input.txt

@@ -0,0 +1,3 @@
+     remote           refid      st t when poll reach   delay   offset  jitter
+==============================================================================
+*uschi5-ntp-002. 10.177.80.46     2 u  101  256   37   51.016  233.010  17.462

plugins/inputs/ntpq/testcases/single_reach_count/telegraf.conf

@@ -0,0 +1,2 @@
+[[inputs.ntpq]]
+    reach_format = "count"

plugins/inputs/ntpq/testcases/single_reach_decimal/expected.out

@@ -0,0 +1 @@
+ntpq,remote=uschi5-ntp-002.,state_prefix=*,refid=10.177.80.46,stratum=2,type=u when=101i,poll=256i,reach=31i,delay=51.016,offset=233.010,jitter=17.462 0

plugins/inputs/ntpq/testcases/single_reach_decimal/input.txt

@@ -0,0 +1,3 @@
+     remote           refid      st t when poll reach   delay   offset  jitter
+==============================================================================
+*uschi5-ntp-002. 10.177.80.46     2 u  101  256   37   51.016  233.010  17.462

plugins/inputs/ntpq/testcases/single_reach_decimal/telegraf.conf

@@ -0,0 +1,2 @@
+[[inputs.ntpq]]
+    reach_format = "decimal"

plugins/inputs/ntpq/testcases/single_reach_octal/expected.out

@@ -0,0 +1 @@
+ntpq,remote=uschi5-ntp-002.,state_prefix=*,refid=10.177.80.46,stratum=2,type=u when=101i,poll=256i,reach=37i,delay=51.016,offset=233.010,jitter=17.462 0

plugins/inputs/ntpq/testcases/single_reach_octal/input.txt

@@ -0,0 +1,3 @@
+     remote           refid      st t when poll reach   delay   offset  jitter
+==============================================================================
+*uschi5-ntp-002. 10.177.80.46     2 u  101  256   37   51.016  233.010  17.462

plugins/inputs/ntpq/testcases/single_reach_octal/telegraf.conf

@@ -0,0 +1,2 @@
+[[inputs.ntpq]]
+    reach_format = "octal"

plugins/inputs/ntpq/testcases/single_reach_ratio/expected.out

@@ -0,0 +1 @@
+ntpq,remote=uschi5-ntp-002.,state_prefix=*,refid=10.177.80.46,stratum=2,type=u when=101i,poll=256i,reach=0.625,delay=51.016,offset=233.010,jitter=17.462 0

plugins/inputs/ntpq/testcases/single_reach_ratio/input.txt

@@ -0,0 +1,3 @@
+     remote           refid      st t when poll reach   delay   offset  jitter
+==============================================================================
+*uschi5-ntp-002. 10.177.80.46     2 u  101  256   37   51.016  233.010  17.462

plugins/inputs/ntpq/testcases/single_reach_ratio/telegraf.conf

@@ -0,0 +1,2 @@
+[[inputs.ntpq]]
+    reach_format = "ratio"