feat: generate the plugins sample config (influxdata#10886)

.circleci/config.yml

@@ -78,6 +78,7 @@ commands:
                 key: windows-go-<< parameters.cache_version >>-{{ checksum "go.sum" }}
             - run: 'sh ./scripts/installgo_windows.sh'
             - run: choco install mingw
+      - run: 'make generate'
       - run: mkdir -p test-results
       - run: ./scripts/install_gotestsum.sh << parameters.os >> << parameters.gotestsum >>
       - unless:
@@ -120,7 +121,7 @@ commands:
                 paths:
                   - 'C:\Go'
                   - 'C:\Users\circleci\project\gotestsum.exe'
-
+      - run: 'make generate-clean'
   package-build:
     parameters:
       type:

Makefile

@@ -109,10 +109,21 @@ versioninfo:
 	go run scripts/generate_versioninfo/main.go; \
 	go generate cmd/telegraf/telegraf_windows.go; \
 
-.PHONY: telegraf
-telegraf:
+.PHONY: generate
+generate:
+	go generate -run="plugindata/main.go$$" ./plugins/inputs/... ./plugins/outputs/... ./plugins/processors/... ./plugins/aggregators/...
+
+.PHONY: generate-clean
+generate-clean:
+	go generate -run="plugindata/main.go --clean" ./plugins/inputs/... ./plugins/outputs/... ./plugins/processors/... ./plugins/aggregators/...
+
+.PHONY: build
+build:
 	go build -ldflags "$(LDFLAGS)" ./cmd/telegraf
 
+.PHONY: telegraf
+telegraf: generate build generate-clean
+
 # Used by dockerfile builds
 .PHONY: go-install
 go-install:
@@ -312,7 +323,7 @@ darwin-arm64:
 include_packages := $(mips) $(mipsel) $(arm64) $(amd64) $(static) $(armel) $(armhf) $(riscv64) $(s390x) $(ppc64le) $(i386) $(windows) $(darwin-amd64) $(darwin-arm64)
 
 .PHONY: package
-package: $(include_packages)
+package: generate $(include_packages) generate-clean
 
 .PHONY: $(include_packages)
 $(include_packages):

config/config.go

@@ -678,23 +678,24 @@ func printConfig(name string, p telegraf.PluginDescriber, op string, commented b
 	if commented {
 		comment = "# "
 	}
-	fmt.Printf("\n%s# %s\n%s[[%s.%s]]", comment, p.Description(), comment, op, name)
 
 	if di.Since != "" {
 		removalNote := ""
 		if di.RemovalIn != "" {
 			removalNote = " and will be removed in " + di.RemovalIn
 		}
-		fmt.Printf("\n%s  ## DEPRECATED: The '%s' plugin is deprecated in version %s%s, %s.", comment, name, di.Since, removalNote, di.Notice)
+		fmt.Printf("\n%s ## DEPRECATED: The '%s' plugin is deprecated in version %s%s, %s.", comment, name, di.Since, removalNote, di.Notice)
 	}
 
 	config := p.SampleConfig()
 	if config == "" {
+		fmt.Printf("\n#[[%s.%s]]", op, name)
 		fmt.Printf("\n%s  # no configuration\n\n", comment)
 	} else {
 		lines := strings.Split(config, "\n")
+		fmt.Print("\n")
 		for i, line := range lines {
-			if i == 0 || i == len(lines)-1 {
+			if i == len(lines)-1 {
 				fmt.Print("\n")
 				continue
 			}

config/config_test.go

@@ -678,7 +678,6 @@ type MockupInputPluginParserOld struct {
 }
 
 func (m *MockupInputPluginParserOld) SampleConfig() string                  { return "Mockup old parser test plugin" }
-func (m *MockupInputPluginParserOld) Description() string                   { return "Mockup old parser test plugin" }
 func (m *MockupInputPluginParserOld) Gather(acc telegraf.Accumulator) error { return nil }
 func (m *MockupInputPluginParserOld) SetParser(parser parsers.Parser)       { m.Parser = parser }
 func (m *MockupInputPluginParserOld) SetParserFunc(f parsers.ParserFunc)    { m.ParserFunc = f }
@@ -690,7 +689,6 @@ type MockupInputPluginParserNew struct {
 }
 
 func (m *MockupInputPluginParserNew) SampleConfig() string                  { return "Mockup old parser test plugin" }
-func (m *MockupInputPluginParserNew) Description() string                   { return "Mockup old parser test plugin" }
 func (m *MockupInputPluginParserNew) Gather(acc telegraf.Accumulator) error { return nil }
 func (m *MockupInputPluginParserNew) SetParser(parser telegraf.Parser)      { m.Parser = parser }
 func (m *MockupInputPluginParserNew) SetParserFunc(f telegraf.ParserFunc)   { m.ParserFunc = f }
@@ -714,7 +712,6 @@ type MockupInputPlugin struct {
 }
 
 func (m *MockupInputPlugin) SampleConfig() string                  { return "Mockup test input plugin" }
-func (m *MockupInputPlugin) Description() string                   { return "Mockup test input plugin" }
 func (m *MockupInputPlugin) Gather(acc telegraf.Accumulator) error { return nil }
 func (m *MockupInputPlugin) SetParser(parser telegraf.Parser)      { m.parser = parser }
 
@@ -730,7 +727,6 @@ type MockupOuputPlugin struct {
 
 func (m *MockupOuputPlugin) Connect() error                        { return nil }
 func (m *MockupOuputPlugin) Close() error                          { return nil }
-func (m *MockupOuputPlugin) Description() string                   { return "Mockup test output plugin" }
 func (m *MockupOuputPlugin) SampleConfig() string                  { return "Mockup test output plugin" }
 func (m *MockupOuputPlugin) Write(metrics []telegraf.Metric) error { return nil }
 

docs/AGGREGATORS.md

@@ -9,10 +9,10 @@ This section is for developers who want to create a new aggregator plugin.
   register themselves.  See below for a quick example.
 * To be available within Telegraf itself, plugins must add themselves to the
   `github.com/influxdata/telegraf/plugins/aggregators/all/all.go` file.
-* The `SampleConfig` function should return valid toml that describes how the
-  plugin can be configured. This is included in `telegraf config`.  Please
-  consult the [Sample Config][] page for the latest style guidelines.
-* The `Description` function should say in one line what this aggregator does.
+* Each plugin requires a file called `<plugin_name>_sample_config.go`, where `<plugin_name>` is replaced with the actual plugin name.
+  Copy the [example template](#sample-configuration-template) into this file, also updating `<plugin_name>` were appropriate.
+  This file is automatically updated during the build process to include the sample configuration from the `README.md`.
+  Please consult the [Sample Config][] page for the latest style guidelines.
 * The Aggregator plugin will need to keep caches of metrics that have passed
   through it. This should be done using the builtin `HashID()` function of
   each metric.
@@ -22,6 +22,8 @@ This section is for developers who want to create a new aggregator plugin.
 ### Aggregator Plugin Example
 
 ```go
+//go:generate go run ../../../tools/generate_plugindata/main.go
+//go:generate go run ../../../tools/generate_plugindata/main.go --clean
 package min
 
 // min.go
@@ -44,26 +46,10 @@ func NewMin() telegraf.Aggregator {
     return m
 }
 
-var sampleConfig = `
-  ## period is the flush & clear interval of the aggregator.
-  period = "30s"
-  ## If true drop_original will drop the original metrics and
-  ## only send aggregates.
-  drop_original = false
-`
-
 func (m *Min) Init() error {
     return nil
 }
 
-func (m *Min) SampleConfig() string {
-    return sampleConfig
-}
-
-func (m *Min) Description() string {
-    return "Keep the aggregate min of each metric passing through."
-}
-
 func (m *Min) Add(in telegraf.Metric) {
     id := in.HashID()
     if _, ok := m.nameCache[id]; !ok {
@@ -127,6 +113,19 @@ func init() {
 }
 ```
 
+### Sample Configuration Template
+
+```go
+//go:generate go run ../../../tools/generate_plugindata/main.go
+//go:generate go run ../../../tools/generate_plugindata/main.go --clean
+// DON'T EDIT; This file is used as a template by tools/generate_plugindata
+package <plugin_package>
+
+func (k *<plugin_struct>) SampleConfig() string {
+    return `{{ .SampleConfig }}`
+}
+```
+
 [telegraf.Aggregator]: https://godoc.org/github.com/influxdata/telegraf#Aggregator
 [Sample Config]: https://github.com/influxdata/telegraf/blob/master/docs/developers/SAMPLE_CONFIG.md
 [Code Style]: https://github.com/influxdata/telegraf/blob/master/docs/developers/CODE_STYLE.md

docs/INPUTS.md

@@ -15,11 +15,10 @@ and submit new inputs.
   themselves.  See below for a quick example.
 - Input Plugins must be added to the
   `github.com/influxdata/telegraf/plugins/inputs/all/all.go` file.
-- The `SampleConfig` function should return valid toml that describes how the
-  plugin can be configured. This is included in `telegraf config`.  Please
-  consult the [Sample Config][] page for the latest style
-  guidelines.
-- The `Description` function should say in one line what this plugin does.
+- Each plugin requires a file called `<plugin_name>_sample_config.go`, where `<plugin_name>` is replaced with the actual plugin name.
+  Copy the [example template](#sample-configuration-template) into this file, also updating `<plugin_name>` were appropriate.
+  This file is automatically updated during the build process to include the sample configuration from the `README.md`.
+  Please consult the [Sample Config][] page for the latest style guidelines.
 - Follow the recommended [Code Style][].
 
 Let's say you've written a plugin that emits metrics about processes on the
@@ -28,10 +27,10 @@ current host.
 ## Input Plugin Example
 
 ```go
+//go:generate go run ../../../tools/generate_plugindata/main.go
+//go:generate go run ../../../tools/generate_plugindata/main.go --clean
 package simple
 
-// simple.go
-
 import (
     "github.com/influxdata/telegraf"
     "github.com/influxdata/telegraf/plugins/inputs"
@@ -42,17 +41,6 @@ type Simple struct {
     Log telegraf.Logger `toml:"-"`
 }
 
-func (s *Simple) Description() string {
-    return "a demo plugin"
-}
-
-func (s *Simple) SampleConfig() string {
-    return `
-  ## Indicate if everything is fine
-  ok = true
-`
-}
-
 // Init is for setup, and validating config.
 func (s *Simple) Init() error {
     return nil
@@ -73,6 +61,17 @@ func init() {
 }
 ```
 
+```go
+//go:generate go run ../../../tools/generate_plugindata/main.go
+//go:generate go run ../../../tools/generate_plugindata/main.go --clean
+// DON'T EDIT; This file is used as a template by tools/generate_plugindata
+package <plugin_package>
+
+func (k *<plugin_struct>) SampleConfig() string {
+    return `{{ .SampleConfig }}`
+}
+```
+
 ### Development
 
 - Run `make static` followed by `make plugin-[pluginName]` to spin up a docker
@@ -101,7 +100,7 @@ You can then utilize the parser internally in your plugin, parsing data as you
 see fit. Telegraf's configuration layer will take care of instantiating and
 creating the `Parser` object.
 
-Add the following to the `SampleConfig()`:
+Add the following to the sample configuration in the README.md:
 
 ```toml
   ## Data format to consume.

docs/OUTPUTS.md

@@ -11,15 +11,17 @@ similar constructs.
   themselves.  See below for a quick example.
 - To be available within Telegraf itself, plugins must add themselves to the
   `github.com/influxdata/telegraf/plugins/outputs/all/all.go` file.
-- The `SampleConfig` function should return valid toml that describes how the
-  plugin can be configured. This is included in `telegraf config`.  Please
-  consult the [Sample Config][] page for the latest style guidelines.
-- The `Description` function should say in one line what this output does.
+- Each plugin requires a file called `<plugin_name>_sample_config.go`, where `<plugin_name>` is replaced with the actual plugin name.
+  Copy the [example template](#sample-configuration-template) into this file, also updating `<plugin_name>` were appropriate.
+  This file is automatically updated during the build process to include the sample configuration from the `README.md`.
+  Please consult the [Sample Config][] page for the latest style guidelines.
 - Follow the recommended [Code Style][].
 
 ## Output Plugin Example
 
 ```go
+//go:generate go run ../../../tools/generate_plugindata/main.go
+//go:generate go run ../../../tools/generate_plugindata/main.go --clean
 package simpleoutput
 
 // simpleoutput.go
@@ -34,16 +36,6 @@ type Simple struct {
     Log telegraf.Logger `toml:"-"`
 }
 
-func (s *Simple) Description() string {
-    return "a demo output"
-}
-
-func (s *Simple) SampleConfig() string {
-    return `
-  ok = true
-`
-}
-
 // Init is for setup, and validating config.
 func (s *Simple) Init() error {
     return nil
@@ -76,6 +68,19 @@ func init() {
 
 ```
 
+### Sample Configuration Template
+
+```go
+//go:generate go run ../../../tools/generate_plugindata/main.go
+//go:generate go run ../../../tools/generate_plugindata/main.go --clean
+// DON'T EDIT; This file is used as a template by tools/generate_plugindata
+package <plugin_package>
+
+func (k *<plugin_struct>) SampleConfig() string {
+    return `{{ .SampleConfig }}`
+}
+```
+
 ## Data Formats
 
 Some output plugins, such as the [file][] plugin, can write in any supported

docs/PROCESSORS.md

@@ -9,18 +9,17 @@ This section is for developers who want to create a new processor plugin.
   themselves.  See below for a quick example.
 * To be available within Telegraf itself, plugins must add themselves to the
   `github.com/influxdata/telegraf/plugins/processors/all/all.go` file.
-* The `SampleConfig` function should return valid toml that describes how the
-  processor can be configured. This is include in the output of `telegraf
-  config`.
-* The `SampleConfig` function should return valid toml that describes how the
-  plugin can be configured. This is included in `telegraf config`.  Please
-  consult the [Sample Config][] page for the latest style guidelines.
-* The `Description` function should say in one line what this processor does.
+* Each plugin requires a file called `<plugin_name>_sample_config.go`, where `<plugin_name>` is replaced with the actual plugin name.
+  Copy the [example template](#sample-configuration-template) into this file, also updating `<plugin_name>` were appropriate.
+  This file is automatically updated during the build process to include the sample configuration from the `README.md`.
+  Please consult the [Sample Config][] page for the latest style guidelines.
 * Follow the recommended [Code Style][].
 
 ## Processor Plugin Example
 
 ```go
+//go:generate go run ../../../tools/generate_plugindata/main.go
+//go:generate go run ../../../tools/generate_plugindata/main.go --clean
 package printer
 
 // printer.go
@@ -36,17 +35,6 @@ type Printer struct {
     Log telegraf.Logger `toml:"-"`
 }
 
-var sampleConfig = `
-`
-
-func (p *Printer) SampleConfig() string {
-    return sampleConfig
-}
-
-func (p *Printer) Description() string {
-    return "Print all metrics that pass through this filter."
-}
-
 // Init is for setup, and validating config.
 func (p *Printer) Init() error {
     return nil
@@ -66,6 +54,19 @@ func init() {
 }
 ```
 
+### Sample Configuration Template
+
+```go
+//go:generate go run ../../../tools/generate_plugindata/main.go
+//go:generate go run ../../../tools/generate_plugindata/main.go --clean
+// DON'T EDIT; This file is used as a template by tools/generate_plugindata
+package <plugin_package>
+
+func (k *<plugin_struct>) SampleConfig() string {
+    return `{{ .SampleConfig }}`
+}
+```
+
 ## Streaming Processors
 
 Streaming processors are a new processor type available to you. They are
@@ -102,17 +103,6 @@ type Printer struct {
     Log telegraf.Logger `toml:"-"`
 }
 
-var sampleConfig = `
-`
-
-func (p *Printer) SampleConfig() string {
-    return sampleConfig
-}
-
-func (p *Printer) Description() string {
-    return "Print all metrics that pass through this filter."
-}
-
 // Init is for setup, and validating config.
 func (p *Printer) Init() error {
     return nil