80 lines
2.2 KiB
Markdown
80 lines
2.2 KiB
Markdown
|
# 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.
|