diff --git a/config/config.go b/config/config.go index e8235b58b..067d38f7c 100644 --- a/config/config.go +++ b/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) } diff --git a/docs/developers/DEPRECATION.md b/docs/developers/DEPRECATION.md index fe262eeed..62b5b986e 100644 --- a/docs/developers/DEPRECATION.md +++ b/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 `[;removal version];` 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 diff --git a/plugins/inputs/amqp_consumer/amqp_consumer.go b/plugins/inputs/amqp_consumer/amqp_consumer.go index abe86bc38..abcf13710 100644 --- a/plugins/inputs/amqp_consumer/amqp_consumer.go +++ b/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"`