CL-Softwares
/
telegraf
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Update deprecation readme (#10529)

This commit is contained in:
Sven Rebhan 2022-01-27 16:59:33 +01:00 committed by GitHub
parent deda716a15
commit bf447f4488
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 36 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
config/config.go
View File

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

42
docs/developers/DEPRECATION.md
View File

@ -13,16 +13,19 @@ decided based on the impact.
## Deprecate plugins ## Deprecate plugins
Add a comment to the plugin's sample config, include the deprecation version Add an entry to the plugins deprecation list (e.g. in `plugins/inputs/deprecations.go`). Include the deprecation version
and any replacement. and any replacement, e.g.
```toml ```golang
[[inputs.logparser]] "logparser": {
## DEPRECATED: The 'logparser' plugin is deprecated in 1.10. Please use the Since: "1.15.0",
## 'tail' plugin with the grok data_format as a replacement. 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 ```markdown
# Logparser Input Plugin # Logparser Input Plugin
@ -34,13 +37,10 @@ Add the deprecation warning to the plugin's README:
[data formats]: /docs/DATA_FORMATS_INPUT.md [data formats]: /docs/DATA_FORMATS_INPUT.md
``` ```
Log a warning message if the plugin is used. If the plugin is a Telegraf will automatically check if a deprecated plugin is configured and print a warning
ServiceInput, place this in the `Start()` function, for regular Input's log it only the first
time the `Gather` function is called.
```go ```text
log.Println("W! [inputs.logparser] The logparser plugin is deprecated in 1.10. " + 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
"Please use the tail plugin with the grok data_format as a replacement.")
``` ```
## Deprecate options ## Deprecate options
@ -54,24 +54,18 @@ version and any replacement.
# url = "amqp://localhost:5672/influxdb" # 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 ```go
type AMQPConsumer struct { 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 ```text
func (a *AMQPConsumer) Init() error { 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
if p.URL != "" {
p.Log.Warnf("Use of deprecated configuration: 'url'; please use the 'brokers' option")
}
return nil
}
``` ```
## Deprecate metrics ## Deprecate metrics

2
plugins/inputs/amqp_consumer/amqp_consumer.go
View File

@ -27,7 +27,7 @@ type semaphore chan empty
// AMQPConsumer is the top level struct for this plugin // AMQPConsumer is the top level struct for this plugin
type AMQPConsumer struct { 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"` Brokers []string `toml:"brokers"`
Username string `toml:"username"` Username string `toml:"username"`
Password string `toml:"password"` Password string `toml:"password"`