fix: Cleanup and add sample.conf embedding (#12244)

plugins/inputs/ethtool/ethtool.go

@@ -1,3 +1,4 @@
+//go:generate ../../../tools/readme_config_includer/generator
 package ethtool
 
 import (

plugins/inputs/ethtool/ethtool_linux.go

@@ -1,4 +1,3 @@
-//go:generate ../../../tools/readme_config_includer/generator
 //go:build linux
 
 package ethtool

plugins/inputs/libvirt/README.md

@@ -2,7 +2,7 @@
 
 The `libvirt` plugin collects statistics about virtualized
 guests on a system by using virtualization libvirt API,
-created by RedHat's Emerging Technology group.  
+created by RedHat's Emerging Technology group.
 Metrics are gathered directly from the hypervisor on a host
 system, which means that Telegraf doesn't have to be installed
 and configured on a guest system.
@@ -33,7 +33,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
 
 ## Configuration
 
-```toml
+```toml @sample.conf
 # The libvirt plugin collects statistics from virtualized guests using virtualization libvirt API.
 [[inputs.libvirt]]
      ## Domain names from which libvirt gather statistics.
@@ -62,6 +62,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
      ## Supported additional statistics: vcpu_mapping
      ## By default (empty or missing array) the plugin will not collect additional statistics.
      # additional_statistics = []
+
 ```
 
 Useful links:
@@ -73,7 +74,7 @@ In cases when one or more of the following occur:
 
 - the global Telegraf variable `interval` is set to a low value (e.g. 1s),
 - a significant number of VMs are monitored,
-- the medium connecting the plugin to the hypervisor is inefficient,  
+- the medium connecting the plugin to the hypervisor is inefficient,
 
 It is possible that following warning in the logs appears:
 `Collection took longer than expected`.
@@ -120,7 +121,7 @@ The metrics are divided into the following groups of statistics:
 - vcpu_mapping - additional statistics
 
 Statistics groups from the plugin corresponds to the grouping of
-metrics directly read from libvirtd using the `virsh domstats` command.  
+metrics directly read from libvirtd using the `virsh domstats` command.
 More details about metrics can be found at the links below:
 
 - [Domain statistics](https://libvirt.org/manpages/virsh.html#domstats)

plugins/inputs/libvirt/libvirt.go

@@ -1,11 +1,13 @@
+//go:generate ../../../tools/readme_config_includer/generator
 package libvirt
 
 import (
 	_ "embed"
 	"fmt"
-	"golang.org/x/sync/errgroup"
 	"sync"
 
+	"golang.org/x/sync/errgroup"
+
 	golibvirt "github.com/digitalocean/go-libvirt"
 	libvirtutils "github.com/thomasklein94/packer-plugin-libvirt/libvirt-utils"
 

plugins/inputs/linux_cpu/README.md

@@ -14,7 +14,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
 ## Configuration
 
 ```toml @sample.conf
-# Collects CPU metrics exposed on Linux
+# Provides Linux CPU metrics
 [[inputs.linux_cpu]]
   ## Path for sysfs filesystem.
   ## See https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt

plugins/inputs/linux_cpu/linux_cpu.go

@@ -1,10 +1,10 @@
+//go:generate ../../../tools/readme_config_includer/generator
 //go:build linux
 
 package linux_cpu
 
 import (
 	_ "embed"
-
 	"fmt"
 	"io"
 	"os"

plugins/inputs/netstat/README.md

@@ -14,7 +14,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
 
 ## Configuration
 
-``` toml
+```toml @sample.conf
 # Read TCP metrics such as established, time wait and sockets counts.
 [[inputs.netstat]]
   # no configuration
@@ -69,3 +69,9 @@ Meta:
 Measurement names:
 
 - udp_socket
+
+## Example Output
+
+```text
+netstat tcp_close=0i,tcp_close_wait=0i,tcp_closing=0i,tcp_established=14i,tcp_fin_wait1=0i,tcp_fin_wait2=0i,tcp_last_ack=0i,tcp_listen=1i,tcp_none=46i,tcp_syn_recv=0i,tcp_syn_sent=0i,tcp_time_wait=0i,udp_socket=10i 1668520568000000000
+```

plugins/inputs/opcua_listener/opcua_listener.go

@@ -1,14 +1,16 @@
+//go:generate ../../../tools/readme_config_includer/generator
 package opcua_listener
 
 import (
 	"context"
 	_ "embed"
+	"time"
+
 	"github.com/influxdata/telegraf"
 	"github.com/influxdata/telegraf/config"
 	"github.com/influxdata/telegraf/plugins/common/opcua"
 	"github.com/influxdata/telegraf/plugins/common/opcua/input"
 	"github.com/influxdata/telegraf/plugins/inputs"
-	"time"
 )
 
 type OpcUaListener struct {

plugins/inputs/opcua_listener/sample.conf

@@ -1,7 +1,7 @@
 # Retrieve data from OPCUA devices
-[[inputs.opcua]]
+[[inputs.opcua_listener]]
   ## Metric name
-  # name = "opcua"
+  # name = "opcua_listener"
   #
   ## OPC UA Endpoint URL
   # endpoint = "opc.tcp://localhost:4840"
@@ -68,14 +68,14 @@
   # ]
   #
   ## Bracketed notation
-  # [[inputs.opcua.nodes]]
+  # [[inputs.opcua_listener.nodes]]
   #   name = "node1"
   #   namespace = ""
   #   identifier_type = ""
   #   identifier = ""
   #   default_tags = { tag1 = "value1", tag2 = "value2" }
   #
-  # [[inputs.opcua.nodes]]
+  # [[inputs.opcua_listener.nodes]]
   #   name = "node2"
   #   namespace = ""
   #   identifier_type = ""
@@ -90,7 +90,7 @@
   ## * Default tags
   ##
   ## Multiple node groups are allowed
-  #[[inputs.opcua.group]]
+  #[[inputs.opcua_listener.group]]
   ## Group Metric name. Overrides the top level name.  If unset, the
   ## top level name is used.
   # name =
@@ -118,24 +118,24 @@
   #]
   #
   ## Bracketed notation
-  # [[inputs.opcua.group.nodes]]
+  # [[inputs.opcua_listener.group.nodes]]
   #   name = "node1"
   #   namespace = ""
   #   identifier_type = ""
   #   identifier = ""
   #   default_tags = { tag1 = "override1", tag2 = "value2" }
   #
-  # [[inputs.opcua.group.nodes]]
+  # [[inputs.opcua_listener.group.nodes]]
   #   name = "node2"
   #   namespace = ""
   #   identifier_type = ""
   #   identifier = ""
 
   ## Enable workarounds required by some devices to work correctly
-  # [inputs.opcua.workarounds]
+  # [inputs.opcua_listener.workarounds]
     ## Set additional valid status codes, StatusOK (0x0) is always considered valid
     # additional_valid_status_codes = ["0xC0"]
 
-  # [inputs.opcua.request_workarounds]
+  # [inputs.opcua_listener.request_workarounds]
     ## Use unregistered reads instead of registered reads
     # use_unregistered_reads = false

plugins/inputs/processes/processes.go

@@ -1,3 +1,4 @@
+//go:generate ../../../tools/readme_config_includer/generator
 package processes
 
 import _ "embed"

plugins/inputs/processes/processes_notwindows.go

@@ -1,4 +1,3 @@
-//go:generate ../../../tools/readme_config_includer/generator
 //go:build !windows
 
 package processes

plugins/inputs/supervisor/README.md

@@ -32,8 +32,9 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
 
 ## Configuration
 
-```toml
-[inputs.supervisor]
+```toml @sample.conf
+# Gathers information about processes that running under supervisor using XML-RPC API
+[[inputs.supervisor]]
   ## Url of supervisor's XML-RPC endpoint if basic auth enabled in supervisor http server,
   ## than you have to add credentials to url (ex. http://login:pass@localhost:9001/RPC2)
   # url="http://localhost:9001/RPC2"

plugins/inputs/supervisor/supervisor.go

@@ -1,3 +1,4 @@
+//go:generate ../../../tools/readme_config_includer/generator
 package supervisor
 
 import (

plugins/outputs/redistimeseries/README.md

@@ -13,19 +13,18 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
 
 ## Configuration
 
-```toml
+```toml @sample.conf
+# Publishes metrics to a redis timeseries server
 [[outputs.redistimeseries]]
   ## The address of the RedisTimeSeries server.
   address = "127.0.0.1:6379"
-  ## password to login Redis
-  password = ""
 
-  ## username (optional)
+  ## Redis ACL credentials
   # username = ""
-  # redis database number (optional, must be an integer)
+  # password = ""
   # database = 0
 
-  ## optional TLS configurations
+  ## Optional TLS Config
   # tls_ca = "/etc/telegraf/ca.pem"
   # tls_cert = "/etc/telegraf/cert.pem"
   # tls_key = "/etc/telegraf/key.pem"

plugins/outputs/redistimeseries/redistimeseries.go

@@ -1,6 +1,8 @@
+//go:generate ../../../tools/readme_config_includer/generator
 package redistimeseries
 
 import (
+	_ "embed"
 	"errors"
 	"fmt"
 
@@ -10,21 +12,8 @@ import (
 	"github.com/influxdata/telegraf/plugins/outputs"
 )
 
-const sampleConfig = `
-  ## The address of the RedisTimeSeries server.
-  address = "127.0.0.1:6379"
-
-  ## Redis ACL credentials
-  # username = ""
-  # password = ""
-  # database = 0
-
-  ## Optional TLS Config
-  # tls_ca = "/etc/telegraf/ca.pem"
-  # tls_cert = "/etc/telegraf/cert.pem"
-  # tls_key = "/etc/telegraf/key.pem"
-  # insecure_skip_verify = false
-`
+//go:embed sample.conf
+var sampleConfig string
 
 type RedisTimeSeries struct {
 	Address  string          `toml:"address"`

plugins/outputs/redistimeseries/sample.conf

@@ -0,0 +1,15 @@
+# Publishes metrics to a redis timeseries server
+[[outputs.redistimeseries]]
+  ## The address of the RedisTimeSeries server.
+  address = "127.0.0.1:6379"
+
+  ## Redis ACL credentials
+  # username = ""
+  # password = ""
+  # database = 0
+
+  ## Optional TLS Config
+  # tls_ca = "/etc/telegraf/ca.pem"
+  # tls_cert = "/etc/telegraf/cert.pem"
+  # tls_key = "/etc/telegraf/key.pem"
+  # insecure_skip_verify = false

scripts/check-plugin-doc-embedding.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+
+plugin="${1}"
+
+if [ ! -d "${plugin}" ]; then
+    echo "ERR: ${plugin} is not a directory"
+    exit 1
+fi
+
+pluginname=$(basename "${plugin}")
+if [[ ":all:" =~ .*:${pluginname}:.* ]]; then
+    echo "INF: ${plugin} ignored"
+    exit 0
+fi
+
+# Check for the sample.conf file
+if [ ! -f "${plugin}/sample.conf" ] && [ "${pluginname}" != "modbus" ]; then
+    echo "ERR: ${plugin} does not contain a sample.conf file"
+    exit 1
+fi
+
+# Check for the sample.conf embedding into the README.md
+readme="^\`\`\`toml @sample.*\.conf\b"
+if  ! grep -q "${readme}" "${plugin}/README.md" ; then
+    echo "ERR: ${plugin} is missing embedding in README"
+    exit 1
+fi
+
+# Check for the generator
+generator="//go:generate ../../../tools/readme_config_includer/generator"
+found=false
+for filename in "${plugin}/"*.go; do
+    if [[ "${filename}" == *_test.go ]]; then
+        continue
+    fi
+    if ! grep -q "SampleConfig(" "${filename}"; then
+        continue
+    fi
+
+    if grep -q "^${generator}\$" "${filename}"; then
+        found=true
+        break
+    fi
+done
+
+if ! ${found}; then
+    echo "ERR: ${plugin} is missing generator statement!"
+    exit 1
+fi
+
+# Check for the embedding
+embedding="//go:embed sample.*\.conf"
+found=false
+for filename in "${plugin}/"*.go; do
+    if [[ "${filename}" == *_test.go ]]; then
+        continue
+    fi
+    if ! grep -q "SampleConfig(" "${filename}"; then
+        continue
+    fi
+
+    if grep -q "^${embedding}\$" "${filename}"; then
+        found=true
+        break
+    fi
+done
+
+if ! ${found}; then
+    echo "ERR: ${plugin} is missing embedding statement!"
+    exit 1
+fi