diff --git a/docs/developers/DEPRECATION.md b/docs/developers/DEPRECATION.md index 62b5b986e..d5ce042ce 100644 --- a/docs/developers/DEPRECATION.md +++ b/docs/developers/DEPRECATION.md @@ -49,7 +49,7 @@ Mark the option as deprecated in the sample config, include the deprecation version and any replacement. ```toml - ## Broker URL + ## Broker to publish to. ## deprecated in 1.7; use the brokers option # url = "amqp://localhost:5672/influxdb" ``` @@ -57,17 +57,22 @@ version and any replacement. In the plugins configuration struct, add a `deprecated` tag to the option: ```go -type AMQPConsumer struct { - URL string `toml:"url" deprecated:"1.7.0;use brokers"` +type AMQP struct { + URL string `toml:"url" deprecated:"1.7.0;use 'brokers' instead"` + Precision string `toml:"precision" deprecated:"1.2.0;option is ignored"` } ``` 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 ```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 +2022-01-26T20:08:15Z W! DeprecationWarning: Option "url" of plugin "outputs.amqp" deprecated since version 1.7.0 and will be removed in 2.0.0: use 'brokers' instead ``` +### Option value + +In the case a specific option value is being deprecated, the method `models.PrintOptionValueDeprecationNotice` needs to be called in the plugin's `Init` method. + ## Deprecate metrics In the README document the metric as deprecated. If there is a replacement field, diff --git a/models/log.go b/models/log.go index c863325da..0829d1de5 100644 --- a/models/log.go +++ b/models/log.go @@ -135,3 +135,14 @@ func PrintOptionDeprecationNotice(level telegraf.Escalation, plugin, option stri ) } } + +func PrintOptionValueDeprecationNotice(level telegraf.Escalation, plugin, option string, value interface{}, info telegraf.DeprecationInfo) { + switch level { + case telegraf.Warn, telegraf.Error: + prefix := deprecationPrefix(level) + log.Printf( + `%s: Value "%+v" for option %q of plugin %q deprecated since version %s and will be removed in %s: %s`, + prefix, value, option, plugin, info.Since, info.RemovalIn, info.Notice, + ) + } +} diff --git a/models/log_test.go b/models/log_test.go index fd43a2bd8..62c357216 100644 --- a/models/log_test.go +++ b/models/log_test.go @@ -177,3 +177,84 @@ func TestPluginOptionDeprecation(t *testing.T) { }) } } + +func TestPluginOptionValueDeprecation(t *testing.T) { + info := telegraf.DeprecationInfo{ + Since: "1.25.0", + RemovalIn: "2.0.0", + Notice: "please check", + } + var tests = []struct { + name string + level telegraf.Escalation + value interface{} + expected string + }{ + { + name: "Error level", + level: telegraf.Error, + value: "foobar", + expected: `Value "foobar" for option "option" of plugin "test" deprecated since version 1.25.0 and will be removed in 2.0.0: please check`, + }, + { + name: "Warn level", + level: telegraf.Warn, + value: "foobar", + expected: `Value "foobar" for option "option" of plugin "test" deprecated since version 1.25.0 and will be removed in 2.0.0: please check`, + }, + { + name: "None", + level: telegraf.None, + expected: ``, + }, + { + name: "nil value", + level: telegraf.Error, + value: nil, + expected: `Value "" for option "option" of plugin "test" deprecated since version 1.25.0 and will be removed in 2.0.0: please check`, + }, + { + name: "Boolean value", + level: telegraf.Error, + value: true, + expected: `Value "true" for option "option" of plugin "test" deprecated since version 1.25.0 and will be removed in 2.0.0: please check`, + }, + { + name: "Integer value", + level: telegraf.Error, + value: 123, + expected: `Value "123" for option "option" of plugin "test" deprecated since version 1.25.0 and will be removed in 2.0.0: please check`, + }, + } + + // Switch the logger to log to a buffer + var buf bytes.Buffer + previous := log.Writer() + log.SetOutput(&buf) + defer log.SetOutput(previous) + + timeout := 1 * time.Second + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + buf.Reset() + PrintOptionValueDeprecationNotice(tt.level, "test", "option", tt.value, info) + + if tt.expected != "" { + require.Eventually(t, func() bool { + return strings.HasSuffix(buf.String(), "\n") + }, timeout, 100*time.Millisecond) + + // Remove the time for comparison + parts := strings.SplitN(strings.TrimSpace(buf.String()), " ", 3) + require.Len(t, parts, 3) + actual := parts[2] + expected := deprecationPrefix(tt.level) + ": " + tt.expected + require.Equal(t, expected, actual) + } else { + time.Sleep(timeout) + require.Empty(t, buf.String()) + } + }) + } +}