feat: add method to inform of deprecated plugin option values (#11987)

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 `<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
 
 ```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,

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,
+		)
+	}
+}

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 "<nil>" 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())
+			}
+		})
+	}
+}