From 973db8c517235a4a6f90657fefb4ea28f024687f Mon Sep 17 00:00:00 2001 From: Sven Rebhan <36194019+srebhan@users.noreply.github.com> Date: Tue, 15 Nov 2022 17:15:35 +0100 Subject: [PATCH] fix: Cleanup and add sample.conf embedding (#12244) --- plugins/inputs/ethtool/ethtool.go | 1 + plugins/inputs/ethtool/ethtool_linux.go | 1 - plugins/inputs/libvirt/README.md | 9 +-- plugins/inputs/libvirt/libvirt.go | 4 +- plugins/inputs/linux_cpu/README.md | 2 +- plugins/inputs/linux_cpu/linux_cpu.go | 2 +- plugins/inputs/netstat/README.md | 8 ++- .../inputs/opcua_listener/opcua_listener.go | 4 +- plugins/inputs/opcua_listener/sample.conf | 18 ++--- plugins/inputs/processes/processes.go | 1 + .../inputs/processes/processes_notwindows.go | 1 - plugins/inputs/supervisor/README.md | 5 +- plugins/inputs/supervisor/supervisor.go | 1 + plugins/outputs/redistimeseries/README.md | 11 ++- .../redistimeseries/redistimeseries.go | 19 ++--- plugins/outputs/redistimeseries/sample.conf | 15 ++++ scripts/check-plugin-doc-embedding.sh | 71 +++++++++++++++++++ 17 files changed, 130 insertions(+), 43 deletions(-) create mode 100644 plugins/outputs/redistimeseries/sample.conf create mode 100755 scripts/check-plugin-doc-embedding.sh diff --git a/plugins/inputs/ethtool/ethtool.go b/plugins/inputs/ethtool/ethtool.go index ae26bc924..0429981cd 100644 --- a/plugins/inputs/ethtool/ethtool.go +++ b/plugins/inputs/ethtool/ethtool.go @@ -1,3 +1,4 @@ +//go:generate ../../../tools/readme_config_includer/generator package ethtool import ( diff --git a/plugins/inputs/ethtool/ethtool_linux.go b/plugins/inputs/ethtool/ethtool_linux.go index baf1e737d..bbdf84f06 100644 --- a/plugins/inputs/ethtool/ethtool_linux.go +++ b/plugins/inputs/ethtool/ethtool_linux.go @@ -1,4 +1,3 @@ -//go:generate ../../../tools/readme_config_includer/generator //go:build linux package ethtool diff --git a/plugins/inputs/libvirt/README.md b/plugins/inputs/libvirt/README.md index b923a828a..0819f6d12 100644 --- a/plugins/inputs/libvirt/README.md +++ b/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) diff --git a/plugins/inputs/libvirt/libvirt.go b/plugins/inputs/libvirt/libvirt.go index bf945554c..5b9c1571e 100644 --- a/plugins/inputs/libvirt/libvirt.go +++ b/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" diff --git a/plugins/inputs/linux_cpu/README.md b/plugins/inputs/linux_cpu/README.md index 21d0c12ce..9e2bdfa90 100644 --- a/plugins/inputs/linux_cpu/README.md +++ b/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 diff --git a/plugins/inputs/linux_cpu/linux_cpu.go b/plugins/inputs/linux_cpu/linux_cpu.go index e13671fbb..a1a974186 100644 --- a/plugins/inputs/linux_cpu/linux_cpu.go +++ b/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" diff --git a/plugins/inputs/netstat/README.md b/plugins/inputs/netstat/README.md index 645c53279..c3b780639 100644 --- a/plugins/inputs/netstat/README.md +++ b/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 +``` diff --git a/plugins/inputs/opcua_listener/opcua_listener.go b/plugins/inputs/opcua_listener/opcua_listener.go index 8e266c440..3e5af78c2 100644 --- a/plugins/inputs/opcua_listener/opcua_listener.go +++ b/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 { diff --git a/plugins/inputs/opcua_listener/sample.conf b/plugins/inputs/opcua_listener/sample.conf index fb9f7487c..f6b9409f2 100644 --- a/plugins/inputs/opcua_listener/sample.conf +++ b/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 diff --git a/plugins/inputs/processes/processes.go b/plugins/inputs/processes/processes.go index ceaeb00c2..2809e94c3 100644 --- a/plugins/inputs/processes/processes.go +++ b/plugins/inputs/processes/processes.go @@ -1,3 +1,4 @@ +//go:generate ../../../tools/readme_config_includer/generator package processes import _ "embed" diff --git a/plugins/inputs/processes/processes_notwindows.go b/plugins/inputs/processes/processes_notwindows.go index e46c5ee9a..2e0444bfb 100644 --- a/plugins/inputs/processes/processes_notwindows.go +++ b/plugins/inputs/processes/processes_notwindows.go @@ -1,4 +1,3 @@ -//go:generate ../../../tools/readme_config_includer/generator //go:build !windows package processes diff --git a/plugins/inputs/supervisor/README.md b/plugins/inputs/supervisor/README.md index d71c769bc..5678760a7 100644 --- a/plugins/inputs/supervisor/README.md +++ b/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" diff --git a/plugins/inputs/supervisor/supervisor.go b/plugins/inputs/supervisor/supervisor.go index e74006434..f76ee130f 100644 --- a/plugins/inputs/supervisor/supervisor.go +++ b/plugins/inputs/supervisor/supervisor.go @@ -1,3 +1,4 @@ +//go:generate ../../../tools/readme_config_includer/generator package supervisor import ( diff --git a/plugins/outputs/redistimeseries/README.md b/plugins/outputs/redistimeseries/README.md index 29bbb8da4..81870ec52 100644 --- a/plugins/outputs/redistimeseries/README.md +++ b/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" diff --git a/plugins/outputs/redistimeseries/redistimeseries.go b/plugins/outputs/redistimeseries/redistimeseries.go index d6f5e520e..04492a967 100644 --- a/plugins/outputs/redistimeseries/redistimeseries.go +++ b/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"` diff --git a/plugins/outputs/redistimeseries/sample.conf b/plugins/outputs/redistimeseries/sample.conf new file mode 100644 index 000000000..9cb48d726 --- /dev/null +++ b/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 diff --git a/scripts/check-plugin-doc-embedding.sh b/scripts/check-plugin-doc-embedding.sh new file mode 100755 index 000000000..06c983cf2 --- /dev/null +++ b/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 \ No newline at end of file