Skip to content

Latest commit

 

History

History
93 lines (66 loc) · 2.95 KB

DEPRECATION.md

File metadata and controls

93 lines (66 loc) · 2.95 KB
Raw

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.

  "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:

# 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

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.

  ## 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:

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

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.

- system
  - fields:
    - uptime_format (string, deprecated in 1.10: use `uptime` field)

Add filtering to the sample config, leave it commented out.

[[inputs.system]]
  ## Uncomment to remove deprecated metrics.
  # fielddrop = ["uptime_format"]