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.