Skip to content

Latest commit

 

History

History
79 lines (54 loc) · 2.21 KB

LOGGING.md

File metadata and controls

79 lines (54 loc) · 2.21 KB
Raw

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.

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.

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:

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:

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.