Adding upstream version 1.34.4.

Signed-off-by: Daniel Baumann <daniel@debian.org>

docs/developers/LOGGING.md

@@ -0,0 +1,79 @@
+# Logging
+
+## Plugin Logging
+
+You can access the Logger for a plugin by defining a field named `Log`.  This
+`Logger` is configured internally with the plugin name and alias so they do not
+need to be specified for each log call.
+
+```go
+type MyPlugin struct {
+    Log telegraf.Logger `toml:"-"`
+}
+```
+
+You can then use this Logger in the plugin.  Use the method corresponding to
+the log level of the message.
+
+```go
+p.Log.Errorf("Unable to write to file: %v", err)
+```
+
+## Agent Logging
+
+In other sections of the code it is required to add the log level and module
+manually:
+
+```go
+log.Printf("E! [agent] Error writing to %s: %v", output.LogName(), err)
+```
+
+## When to Log
+
+Log a message if an error occurs but the plugin can continue working.  For
+example if the plugin handles several servers and only one of them has a fatal
+error, it can be logged as an error.
+
+Use logging judiciously for debug purposes.  Since Telegraf does not currently
+support setting the log level on a per module basis, it is especially important
+to not over do it with debug logging.
+
+If the plugin is listening on a socket, log a message with the address of the socket:
+
+```go
+p.log.InfoF("Listening on %s://%s", protocol, l.Addr())
+```
+
+## When not to Log
+
+Don't use logging to emit performance data or other meta data about the plugin,
+instead use the `internal` plugin and the `selfstats` package.
+
+Don't log fatal errors in the plugin that require the plugin to return, instead
+return them from the function and Telegraf will handle the logging.
+
+Don't log for static configuration errors, check for them in a plugin `Init()`
+function and return an error there.
+
+Don't log a warning every time a plugin is called for situations that are
+normal on some systems.
+
+## Log Level
+
+The log level is indicated by a single character at the start of the log
+message.  Adding this prefix is not required when using the Plugin Logger.
+
+- `D!` Debug
+- `I!` Info
+- `W!` Warning
+- `E!` Error
+
+## Style
+
+Log messages should be capitalized and be a single line.
+
+If it includes data received from another system or process, such as the text
+of an error message, the text should be quoted with `%q`.
+
+Use the `%v` format for the Go error type instead of `%s` to ensure a nil error
+is printed.