github.com/influxdata/telegraf@v1.30.3/docs/developers/LOGGING.md (about) 1 # Logging 2 3 ## Plugin Logging 4 5 You can access the Logger for a plugin by defining a field named `Log`. This 6 `Logger` is configured internally with the plugin name and alias so they do not 7 need to be specified for each log call. 8 9 ```go 10 type MyPlugin struct { 11 Log telegraf.Logger `toml:"-"` 12 } 13 ``` 14 15 You can then use this Logger in the plugin. Use the method corresponding to 16 the log level of the message. 17 18 ```go 19 p.Log.Errorf("Unable to write to file: %v", err) 20 ``` 21 22 ## Agent Logging 23 24 In other sections of the code it is required to add the log level and module 25 manually: 26 27 ```go 28 log.Printf("E! [agent] Error writing to %s: %v", output.LogName(), err) 29 ``` 30 31 ## When to Log 32 33 Log a message if an error occurs but the plugin can continue working. For 34 example if the plugin handles several servers and only one of them has a fatal 35 error, it can be logged as an error. 36 37 Use logging judiciously for debug purposes. Since Telegraf does not currently 38 support setting the log level on a per module basis, it is especially important 39 to not over do it with debug logging. 40 41 If the plugin is listening on a socket, log a message with the address of the socket: 42 43 ```go 44 p.log.InfoF("Listening on %s://%s", protocol, l.Addr()) 45 ``` 46 47 ## When not to Log 48 49 Don't use logging to emit performance data or other meta data about the plugin, 50 instead use the `internal` plugin and the `selfstats` package. 51 52 Don't log fatal errors in the plugin that require the plugin to return, instead 53 return them from the function and Telegraf will handle the logging. 54 55 Don't log for static configuration errors, check for them in a plugin `Init()` 56 function and return an error there. 57 58 Don't log a warning every time a plugin is called for situations that are 59 normal on some systems. 60 61 ## Log Level 62 63 The log level is indicated by a single character at the start of the log 64 message. Adding this prefix is not required when using the Plugin Logger. 65 66 - `D!` Debug 67 - `I!` Info 68 - `W!` Warning 69 - `E!` Error 70 71 ## Style 72 73 Log messages should be capitalized and be a single line. 74 75 If it includes data received from another system or process, such as the text 76 of an error message, the text should be quoted with `%q`. 77 78 Use the `%v` format for the Go error type instead of `%s` to ensure a nil error 79 is printed.