94 lines
3 KiB
Markdown
94 lines
3 KiB
Markdown
|
# Deprecation
|
||
|
|
|
||
|
|
Deprecation is the primary tool for making changes in Telegraf. A deprecation
|
||
|
|
indicates that the community should move away from using a feature, and
|
||
|
|
documents that the feature will be removed in the next major update (2.0).
|
||
|
|
|
||
|
|
Key to deprecation is that the feature remains in Telegraf and the behavior is
|
||
|
|
not changed.
|
||
|
|
|
||
|
|
We do not have a strict definition of a breaking change. All code changes
|
||
|
|
change behavior, the decision to deprecate or make the change immediately is
|
||
|
|
decided based on the impact.
|
||
|
|
|
||
|
|
## Deprecate plugins
|
||
|
|
|
||
|
|
Add an entry to the plugins deprecation list (e.g. in `plugins/inputs/deprecations.go`). Include the deprecation version
|
||
|
|
and any replacement, e.g.
|
||
|
|
|
||
|
|
```golang
|
||
|
|
"logparser": {
|
||
|
|
Since: "1.15.0",
|
||
|
|
Notice: "use 'inputs.tail' with 'grok' data format instead",
|
||
|
|
},
|
||
|
|
```
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
### **Deprecated in 1.10**: Please use the [tail][] plugin along with the
|
||
|
|
`grok` [data format][].
|
||
|
|
|
||
|
|
[tail]: /plugins/inputs/tail/README.md
|
||
|
|
[data formats]: /docs/DATA_FORMATS_INPUT.md
|
||
|
|
```
|
||
|
|
|
||
|
|
Telegraf will automatically check if a deprecated plugin is configured and print a warning
|
||
|
|
|
||
|
|
```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
|
||
|
|
|
||
|
|
Mark the option as deprecated in the sample config, include the deprecation
|
||
|
|
version and any replacement.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
## Broker to publish to.
|
||
|
|
## deprecated in 1.7; use the brokers option
|
||
|
|
# url = "amqp://localhost:5672/influxdb"
|
||
|
|
```
|
||
|
|
|
||
|
|
In the plugins configuration struct, add a `deprecated` tag to the option:
|
||
|
|
|
||
|
|
```go
|
||
|
|
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 "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,
|
||
|
|
tag, or measurement then mention it.
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
- system
|
||
|
|
- fields:
|
||
|
|
- uptime_format (string, deprecated in 1.10: use `uptime` field)
|
||
|
|
```
|
||
|
|
|
||
|
|
Add filtering to the sample config, leave it commented out.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[[inputs.system]]
|
||
|
|
## Uncomment to remove deprecated metrics.
|
||
|
|
# fieldexclude = ["uptime_format"]
|
||
|
|
```
|