Adding upstream version 1.34.4.

Signed-off-by: Daniel Baumann <daniel@debian.org>
2025-05-24 07:26:29 +02:00 · 2025-05-24 07:26:29 +02:00 · 4978089aab
commit 4978089aab
parent e393c3af3f
4963 changed files with 677545 additions and 0 deletions
--- a/docs/developers/DEPRECATION.md
+++ b/docs/developers/DEPRECATION.md
@ -0,0 +1,93 @@
+# 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"]
+```