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  ```