DEPRECATION.md

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.

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

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

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.

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

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:

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.

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