89 lines
2.6 KiB
Markdown
89 lines
2.6 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 a comment to the plugin's sample config, include the deprecation version
|
||
|
|
and any replacement.
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[[inputs.logparser]]
|
||
|
|
## DEPRECATED: The 'logparser' plugin is deprecated in 1.10. Please use the
|
||
|
|
## 'tail' plugin with the grok data_format as a replacement.
|
||
|
|
```
|
||
|
|
|
||
|
|
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
|
||
|
|
```
|
||
|
|
|
||
|
|
Log a warning message if the plugin is used. If the plugin is a
|
||
|
|
ServiceInput, place this in the `Start()` function, for regular Input's log it only the first
|
||
|
|
time the `Gather` function is called.
|
||
|
|
```go
|
||
|
|
log.Println("W! [inputs.logparser] The logparser plugin is deprecated in 1.10. " +
|
||
|
|
"Please use the tail plugin with the grok data_format as a replacement.")
|
||
|
|
```
|
||
|
|
## Deprecate options
|
||
|
|
|
||
|
|
Mark the option as deprecated in the sample config, include the deprecation
|
||
|
|
version and any replacement.
|
||
|
|
```toml
|
||
|
|
## Broker URL
|
||
|
|
## deprecated in 1.7; use the brokers option
|
||
|
|
# url = "amqp://localhost:5672/influxdb"
|
||
|
|
```
|
||
|
|
|
||
|
|
In the plugins configuration struct, mention that the option is deprecated:
|
||
|
|
|
||
|
|
```go
|
||
|
|
type AMQPConsumer struct {
|
||
|
|
URL string `toml:"url"` // deprecated in 1.7; 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:
|
||
|
|
```go
|
||
|
|
func (a *AMQPConsumer) Init() error {
|
||
|
|
if p.URL != "" {
|
||
|
|
p.Log.Warnf("Use of deprecated configuration: 'url'; please use the 'brokers' option")
|
||
|
|
}
|
||
|
|
return nil
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## 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.
|
||
|
|
# fielddrop = ["uptime_format"]
|
||
|
|
```
|