docs: Update deprecation readme (#10529)

config/config.go

@@ -547,7 +547,7 @@ func printFilteredProcessors(processorFilters []string, commented bool) {
 	for _, pname := range pnames {
 		creator := processors.Processors[pname]
 		output := creator()
-		printConfig(pname, output, "processors", commented)
+		printConfig(pname, output, "processors", commented, processors.Deprecations[pname])
 	}
 }
 
@@ -565,7 +565,7 @@ func printFilteredAggregators(aggregatorFilters []string, commented bool) {
 	for _, aname := range anames {
 		creator := aggregators.Aggregators[aname]
 		output := creator()
-		printConfig(aname, output, "aggregators", commented)
+		printConfig(aname, output, "aggregators", commented, aggregators.Deprecations[aname])
 	}
 }
 
@@ -603,7 +603,7 @@ func printFilteredInputs(inputFilters []string, commented bool) {
 			continue
 		}
 
-		printConfig(pname, input, "inputs", commented)
+		printConfig(pname, input, "inputs", commented, inputs.Deprecations[pname])
 	}
 
 	// Print Service Inputs
@@ -614,7 +614,7 @@ func printFilteredInputs(inputFilters []string, commented bool) {
 
 	fmt.Printf(serviceInputHeader)
 	for _, name := range servInputNames {
-		printConfig(name, servInputs[name], "inputs", commented)
+		printConfig(name, servInputs[name], "inputs", commented, inputs.Deprecations[name])
 	}
 }
 
@@ -632,7 +632,7 @@ func printFilteredOutputs(outputFilters []string, commented bool) {
 	for _, oname := range onames {
 		creator := outputs.Outputs[oname]
 		output := creator()
-		printConfig(oname, output, "outputs", commented)
+		printConfig(oname, output, "outputs", commented, outputs.Deprecations[oname])
 	}
 }
 
@@ -646,13 +646,20 @@ func printFilteredGlobalSections(sectionFilters []string) {
 	}
 }
 
-func printConfig(name string, p telegraf.PluginDescriber, op string, commented bool) {
+func printConfig(name string, p telegraf.PluginDescriber, op string, commented bool, di telegraf.DeprecationInfo) {
 	comment := ""
 	if commented {
 		comment = "# "
 	}
-	fmt.Printf("\n%s# %s\n%s[[%s.%s]]", comment, p.Description(), comment,
-		op, name)
+	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)
+	}
 
 	config := p.SampleConfig()
 	if config == "" {
@@ -681,7 +688,7 @@ func sliceContains(name string, list []string) bool {
 // PrintInputConfig prints the config usage of a single input.
 func PrintInputConfig(name string) error {
 	if creator, ok := inputs.Inputs[name]; ok {
-		printConfig(name, creator(), "inputs", false)
+		printConfig(name, creator(), "inputs", false, inputs.Deprecations[name])
 	} else {
 		return fmt.Errorf("Input %s not found", name)
 	}
@@ -691,7 +698,7 @@ func PrintInputConfig(name string) error {
 // PrintOutputConfig prints the config usage of a single output.
 func PrintOutputConfig(name string) error {
 	if creator, ok := outputs.Outputs[name]; ok {
-		printConfig(name, creator(), "outputs", false)
+		printConfig(name, creator(), "outputs", false, outputs.Deprecations[name])
 	} else {
 		return fmt.Errorf("Output %s not found", name)
 	}

docs/developers/DEPRECATION.md

@@ -13,16 +13,19 @@ decided based on the impact.
 
 ## Deprecate plugins
 
-Add a comment to the plugin's sample config, include the deprecation version
-and any replacement.
+Add an entry to the plugins deprecation list (e.g. in `plugins/inputs/deprecations.go`). Include the deprecation version
+and any replacement, e.g.
 
-```toml
-[[inputs.logparser]]
-  ## DEPRECATED: The 'logparser' plugin is deprecated in 1.10.  Please use the
-  ## 'tail' plugin with the grok data_format as a replacement.
+```golang
+  "logparser": {
+    Since:  "1.15.0",
+    Notice: "use 'inputs.tail' with 'grok' data format instead",
+  },
 ```
 
-Add the deprecation warning to the plugin's README:
+The entry can contain an optional `RemovalIn` field specifying the planned version for removal of the plugin.
+
+Also add the deprecation warning to the plugin's README:
 
 ```markdown
 # Logparser Input Plugin
@@ -34,13 +37,10 @@ Add the deprecation warning to the plugin's README:
 [data formats]: /docs/DATA_FORMATS_INPUT.md
 ```
 
-Log a warning message if the plugin is used.  If the plugin is a
-ServiceInput, place this in the `Start()` function, for regular Input's log it only the first
-time the `Gather` function is called.
+Telegraf will automatically check if a deprecated plugin is configured and print a warning
 
-```go
-log.Println("W! [inputs.logparser] The logparser plugin is deprecated in 1.10. " +
-    "Please use the tail plugin with the grok data_format as a replacement.")
+```text
+2022-01-26T20:08:15Z W! DeprecationWarning: Plugin "inputs.logparser" deprecated since version 1.15.0 and will be removed in 2.0.0: use 'inputs.tail' with 'grok' data format instead
 ```
 
 ## Deprecate options
@@ -54,24 +54,18 @@ version and any replacement.
   # url = "amqp://localhost:5672/influxdb"
 ```
 
-In the plugins configuration struct, mention that the option is deprecated:
+In the plugins configuration struct, add a `deprecated` tag to the option:
 
 ```go
 type AMQPConsumer struct {
-    URL string `toml:"url"` // deprecated in 1.7; use brokers
+    URL string `toml:"url" deprecated:"1.7.0;use brokers"`
 }
 ```
 
-Finally, use the plugin's `Init() error` method to display a log message at warn level.  The message should include the offending configuration option and any suggested replacement:
+The `deprecated` tag has the format `<since version>[;removal version];<notice>` where the `removal version` is optional. The specified deprecation info will automatically displayed by Telegraf if the option is used in the config
 
-```go
-func (a *AMQPConsumer) Init() error {
-    if p.URL != "" {
-        p.Log.Warnf("Use of deprecated configuration: 'url'; please use the 'brokers' option")
-    }
-
-    return nil
-}
+```text
+2022-01-26T20:08:15Z W! DeprecationWarning: Option "url" of plugin "inputs.amqp_consumer" deprecated since version 1.7.0 and will be removed in 2.0.0: use brokers
 ```
 
 ## Deprecate metrics

plugins/inputs/amqp_consumer/amqp_consumer.go

@@ -27,7 +27,7 @@ type semaphore chan empty
 
 // AMQPConsumer is the top level struct for this plugin
 type AMQPConsumer struct {
-	URL                    string            `toml:"url"` // deprecated in 1.7; use brokers
+	URL                    string            `toml:"url" deprecated:"1.7.0;use brokers"`
 	Brokers                []string          `toml:"brokers"`
 	Username               string            `toml:"username"`
 	Password               string            `toml:"password"`