github.com/influxdata/telegraf@v1.30.3/docs/developers/DEPRECATION.md (about) 1 # Deprecation 2 3 Deprecation is the primary tool for making changes in Telegraf. A deprecation 4 indicates that the community should move away from using a feature, and 5 documents that the feature will be removed in the next major update (2.0). 6 7 Key to deprecation is that the feature remains in Telegraf and the behavior is 8 not changed. 9 10 We do not have a strict definition of a breaking change. All code changes 11 change behavior, the decision to deprecate or make the change immediately is 12 decided based on the impact. 13 14 ## Deprecate plugins 15 16 Add an entry to the plugins deprecation list (e.g. in `plugins/inputs/deprecations.go`). Include the deprecation version 17 and any replacement, e.g. 18 19 ```golang 20 "logparser": { 21 Since: "1.15.0", 22 Notice: "use 'inputs.tail' with 'grok' data format instead", 23 }, 24 ``` 25 26 The entry can contain an optional `RemovalIn` field specifying the planned version for removal of the plugin. 27 28 Also add the deprecation warning to the plugin's README: 29 30 ```markdown 31 # Logparser Input Plugin 32 33 ### **Deprecated in 1.10**: Please use the [tail][] plugin along with the 34 `grok` [data format][]. 35 36 [tail]: /plugins/inputs/tail/README.md 37 [data formats]: /docs/DATA_FORMATS_INPUT.md 38 ``` 39 40 Telegraf will automatically check if a deprecated plugin is configured and print a warning 41 42 ```text 43 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 44 ``` 45 46 ## Deprecate options 47 48 Mark the option as deprecated in the sample config, include the deprecation 49 version and any replacement. 50 51 ```toml 52 ## Broker to publish to. 53 ## deprecated in 1.7; use the brokers option 54 # url = "amqp://localhost:5672/influxdb" 55 ``` 56 57 In the plugins configuration struct, add a `deprecated` tag to the option: 58 59 ```go 60 type AMQP struct { 61 URL string `toml:"url" deprecated:"1.7.0;use 'brokers' instead"` 62 Precision string `toml:"precision" deprecated:"1.2.0;option is ignored"` 63 } 64 ``` 65 66 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 67 68 ```text 69 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 70 ``` 71 72 ### Option value 73 74 In the case a specific option value is being deprecated, the method `models.PrintOptionValueDeprecationNotice` needs to be called in the plugin's `Init` method. 75 76 ## Deprecate metrics 77 78 In the README document the metric as deprecated. If there is a replacement field, 79 tag, or measurement then mention it. 80 81 ```markdown 82 - system 83 - fields: 84 - uptime_format (string, deprecated in 1.10: use `uptime` field) 85 ``` 86 87 Add filtering to the sample config, leave it commented out. 88 89 ```toml 90 [[inputs.system]] 91 ## Uncomment to remove deprecated metrics. 92 # fieldexclude = ["uptime_format"] 93 ```