doc.go

// Package rlog
// A simple Golang logger with lots of features and no external dependencies
//
//
// Rlog is a simple logging package, rich in features. It is configurable 'from
// the outside' via environment variables and/or config file and has no
// dependencies other than the standard Golang library.
//
// It is called "rlog", because it was originally written for the
// [Romana project](https://github.com/romana/romana).
//
//
// FEATURES
//
// * Logging configuration of a running process can be modified, without needing
//   to restart it. This allows for on-demand finer level logging, if a process
//   starts to experience issues, for example.
//
// * Is configured through environment variables or config file: No need to call a
//   special init function of some kind to initialize and configure the logger.
//
// * A new config file can be specified and applied programmatically at any time.
//
// * Offers familiar and easy to use log functions for the usual levels: Debug,
//   Info, Warn, Error and Critical.
//
// * Offers an additional multi level logging facility with arbitrary depth,
//   called Trace.
//
// * Log and trace levels can be configured separately for the individual files
//   that make up your executable.
//
// * Every log function comes in a 'plain' version (to be used like Println)
//   and in a formatted version (to be used like Printf). For example, there
//   is Debug() and Debugf(), which takes a format string as first parameter.
//
// * Can be configured to print caller info (process ID, module filename and line,
//   function name). In addition, can also print the goroutine ID in the caller
//   info.
//
// * Has NO external dependencies, except things contained in the standard Go
//   library.
//
// * Fully configurable date/time format.
//
// * Logging of date and time can be disabled (useful in case of systemd, which
//   adds its own time stamps in its log database).
//
// * By default logs to stderr or stdout. A logfile can be configured via
//   environment variable. Output may happen exclusively to the logfile or in
//   addition to the output on stderr/stdout. Also, a different output stream
//   or file can be specified from within your programs at any time.
//
//
// DEFAULTS
//
// Rlog comes with reasonable defaults, so you can just start using it without any
// configuration at all. By default:
//
// * Log level set to INFO.
//
// * Trace messages are not logged.
//
// * Time stamps are logged with each message.
//
// * No caller information.
//
// * Output is sent to stderr.
//
// All those defaults can easily be changed through environment variables or the
// config file.
//
//
// CONTROLLING RLOG THROUGH ENVIRONMENT OR CONFIG FILE VARIABLES
//
// Rlog is configured via the following settings, which may either be defined as
// environment variables or via a config file.
//
// * RLOG_LOG_LEVEL: Set to "DEBUG", "INFO", "WARN", "ERROR", "CRITICAL" or
//   "NONE". Any message of a level >= than what's configured will be printed. If
//   this is not defined it will default to "INFO". If it is set to "NONE" then
//   all logging is disabled, except Trace logs, which are controlled via a
//   separate variable. In addition, log levels can be set for individual files
//   (see below for more information). Default: INFO - meaning that INFO and
//   higher is logged.
//
// * RLOG_TRACE_LEVEL: "Trace" log messages take an additional numeric level as
//   first parameter. The user can specify an arbitrary number of levels. Set
//   RLOG_TRACE_LEVEL to a number. All Trace messages with a level <=
//   RLOG_TRACE_LEVEL will be printed. If this variable is undefined, or set to -1
//   then no Trace messages are printed. The idea is that the higher the
//   RLOG_TRACE_LEVEL value, the more 'chatty' and verbose the Trace message
//   output becomes. In addition, trace levels can be set for individual files
//   (see below for more information). Default: Not set - meaning that no trace
//   messages are logged.
//
// * RLOG_CALLER_INFO: If this variable is set to "1", "yes" or something else
//   that evaluates to 'true' then the message also contains the caller
//   information, consisting of the process ID, file and line number as well as
//   function name from which the log message was called. Default: No - meaning
//   that no caller info is logged.
//
// * RLOG_GOROUTINE_ID: If this variable is set to "1", "yes" or something else
//   that evaluates to 'true' AND the printing of caller info is requested, then
//   the caller info contains the goroutine ID, separated from the process ID by a
//   ':'. Note that calculation of the goroutine ID has a performance impact, so
//   please only enable this option if needed.
//
// * RLOG_TIME_FORMAT: Use this variable to customize the date/time format. The
//   format is specified either by the well known formats listed in
//   https://golang.org/src/time/format.go, for example "UnixDate" or "RFC3339".
//   Or as an example date/time output, which is described here:
//   https://golang.org/pkg/time/#Time.Format Default: Not set - formatted
//   according to RFC3339.
//
// * RLOG_LOG_NOTIME: If this variable is set to "1", "yes" or something else
//   that evaluates to 'true' then no date/time stamp is logged with each log
//   message. This is useful in environments that use systemd where access to the
//   logs via their logging tools already gives you time stamps. Default: No -
//   meaning that time/date is logged.
//
// * RLOG_LOG_FILE: Provide a filename here to determine if the logfile should
//   be written to a file, in addition to the output stream specified in
//   RLOG_LOG_STREAM. Default: Not set - meaning that output is not written to a
//   file.
//
// * RLOG_LOG_STREAM: Use this to direct the log output to a different output
//   stream, instead of stderr. This accepts three values: "stderr", "stdout" or
//   "none". If either stderr or stdout is defined here AND a logfile is specified
//   via RLOG_LOG_FILE then the output is sent to both. Default: Not set -
//   meaning the output goes to stderr.
//
// There are two more settings, related to the configuration file, which can only
// be set via environment variables.
//
// * RLOG_CONF_FILE: If this variable is set then rlog looks for the config
//   file at the specified location, which needs to be the path of the
//   file. If this variable is not defined, then rlog will look for the config
//   file in /etc/rlog/<your-executable-name>.conf. Therefore, by default every
//   executable has its own config file. By setting this variable, you could
//   force multiple processes to share the same config file.
//   Note that with the SetConfFile() function you can specify a new config file
//   programmatically at any time, even with a relative path.
//
// * RLOG_CONF_CHECK_INTERVAL: Number of seconds between checking whether the
//   config file has changed. By default, this is set to 15 seconds. This means
//   that within 15 seconds a changed logging configuration in the config file
//   will take effect. Note that this check is only performed when a log message
//   is actually written. If the program does nothing or doesn't log messages, the
//   config file won't be read. If there is no config file or it has been removed
//   then the configuration from the environment variables is used. Set this value
//   to 0 in order to switch off the regular config file checking: The config file
//   will then only be read once at the start.
//
// Please note! If these environment variables have incorrect or misspelled
// values then they will be silently ignored and a default value will be used.
//
//
// USING THE CONFIG FILE
//
// A config file for rlog is entirely optional, since rlog works just fine even
// without it. However, it does provide you with a very neat feature: You can
// change the logging configuration of a running program from the outside and
// without having to restart it!
//
// When rlog is imported it starts out with the defaults described above. It then
// takes an initial configuration from environment variables, which may override
// the default values. Next, it looks for the rlog config file. If it cannot find
// the config file it will quietly continue without error. If the config file is
// found then the configuration from environment variables is combined with the
// configuration from the config file. More about how this combination works, and
// what takes precedence, in a moment.
//
// CONFIG FILE LOCATION
//
// The path for the config file can be set via the RLOG_CONF_FILE
// environment variable. Absent that, rlog looks for a config file in
// /etc/rlog/<your-executable-name>.conf. This means that you can easily provide
// different logging configurations for each of your processes.
//
// A new config file location can also be specified at any time via the
// SetConfFile() function. An absolute or relative path may be specfied with that
// function.
//
// CONFIG FILE FORMAT
//
// The format of the config file is simple. Each setting is referred to by the
// same name as the environment variable. So, your config file may look like this:
//
//     # Comment lines start with a '#'
//     RLOG_LOG_LEVEL  = WARN
//     RLOG_LOG_STREAM = stdout
//     RLOG_TIME_FORMAT= UnixDate
//     RLOG_LOG_FILE   = /var/log/myapp.log
//
// A few notes about config file formatting:
//
// * Empty lines, or lines starting with '#' are ignored.
//
// * Leading and trailing spaces in lines are removed.
//
// * Everything after the first '=' will be taken as the value of the setting.
//
// * Leading and trailing spaces in values are removed.
//
// * Spaces or further '=' characters within values are taken as they are.
//
// COMBINING CONFIGURATION FROM ENVIRONMENT VARIABLES AND CONFIG FILE
//
// Generally, environment variables take precedence. Assume you have set a log
// level of INFO via the RLOG_LOG_LEVEL variable. This value will be used,
// even if you specified DEBUG in the config file, since an explicitly set
// environment variable takes precedence.
//
// There are only two cases when a config file value takes precedence:
//
// 1. If you do not have an explicit value set in the environment variable. For
//    example, if you do not have the RLOG_LOG_LEVEL environment variable defined
//    at all, or if it is set to the empty string.
//
// 2. If you apply a '!' as prefix in the config file. That marks this value as
//    higher priority than the environment variable. Consider the following config
//    file as example. Here RLOG_LOG_LEVEL and RLOG_TIME_FORMAT will take
//    precedence over whatever was defined in the environment variables.
//
// An example of using '!' in the config file:
//
//     !RLOG_LOG_LEVEL=WARN
//     RLOG_LOG_STREAM=stdout
//     !RLOG_TIME_FORMAT=UnixDate
//     RLOG_LOG_FILE=/var/log/myapp.log
//
//
// UPDATING LOGGING CONFIG FROM THE OUTSIDE: BY MODIFYING THE CONFIG FILE
//
// Every time you log a message and at least RLOG_CONF_CHECK_INTERVAL seconds have
// elapsed since the last reading of the config file, rlog will automatically
// re-read the content of the conf file and re-apply the configuration it finds
// there over the initial configuration, which was based on the environment
// variables.
//
// You can always just delete the config file to go back to the configuration
// based solely on environment variables.
//
// UPDATING LOGGING CONFIG FROM THE INSIDE: BY MODIFYING YOUR OWN ENVIRONMENT VARIABLES
//
// A running program may also change its rlog configuration on its own: The
// process can use the os.Setenv() function to modify its own environment
// variables and then call rlog.UpdatEnv() to reapply the settings
// from the environment variables. The examples/example.go file shows how this
// is done. But in short:
//
//     // Programmatically change an rlog setting from within the program
//     os.Setenv("RLOG_LOG_LEVEL", "DEBUG")
//     rlog.UpdateEnv()
//
// Note that this will not change rlog behaviour if the value for this config
// setting was specified with a '!' in the config file.
//
//
// PER FILE LEVEL LOG AND TRACE LEVELS
//
// In most cases you might want to set just a single log or trace level, which is
// then applied to all log messages in your program. With environment variables,
// you would set it like this:
//
//     export RLOG_LOG_LEVEL=INFO
//     export RLOG_TRACE_LEVEL=3
//
// However, with rlog the log and trace levels can not only be configured
// 'globally' with a single value, but can also independently be set for the
// individual module files that were compiled into your executable. This is useful
// if enabling high trace levels or DEBUG logging for the entire executable would
// fill up logs or consume too many resources.
//
// For example, if your executable is compiled out of several files and one of
// those files is called 'example.go' then you could set log levels like this:
//
//     export RLOG_LOG_LEVEL=INFO,example.go=DEBUG
//
// This sets the global log level to INFO, but for the messages originating from
// the module file 'example.go' it is DEBUG.
//
// Similarly, you can set trace levels for individual module files:
//
//     export RLOG_TRACE_LEVEL=example.go=5,2
//
// This sets a trace level of 5 for example.go and 2 for everyone else.
//
// More examples:
//
//     # DEBUG level for all files whose name starts with 'ex', WARNING level for
//     # everyone else.
//     export RLOG_LOG_LEVEL=WARN,ex*=DEBUG
//
//     # DEBUG level for example.go, INFO for everyone else, since INFO is the
//     # default level if nothing is specified.
//     export RLOG_LOG_LEVEL=example.go=DEBUG
//
//     # DEBUG level for example.go, no logging for anyone else.
//     export RLOG_LOG_LEVEL=NONE,example.go=DEBUG
//
//     # Multiple files' levels can be specified at once.
//     export RLOG_LOG_LEVEL=NONE,example.go=DEBUG,foo.go=INFO
//
//     # The default log level can appear anywhere in the list.
//     export RLOG_LOG_LEVEL=example.go=DEBUG,INFO,foo.go=WARN
//
// Note that as before, if in RLOG_LOG_LEVEL no global log level is specified then
// INFO is assumed to be the global log level. If in RLOG_TRACE_LEVEL no global
// trace level is specified then -1 (no trace output) is assumed as the global
// trace level.
//
//
// USAGE EXAMPLE
//
//     import "github.com/romana/rlog"
//
//     func main() {
//  	   rlog.Debug("A debug message: For the developer")
//  	   rlog.Info("An info message: Normal operation messages")
//  	   rlog.Warn("A warning message: Intermittent issues, high load, etc.")
//  	   rlog.Error("An error message: An error occurred, I will recover.")
//  	   rlog.Critical("A critical message: That's it! I give up!")
//  	   rlog.Trace(2, "A trace message")
//  	   rlog.Trace(3, "An even deeper trace message")
//     }
//
// For a more interesting example, please check out 'examples/example.go'.
//
//
// SAMPLE OUTPUT
//
// With time stamp, trace to level 2, log level WARNING, no caller info:
//
//     $ export RLOG_LOG_LEVEL=WARN
//     $ export RLOG_TRACE_LEVEL=2
//     $ go run examples/example.go
//
//     2017-11-16T08:06:56+13:00 WARN     : Warning level log message
//     2017-11-16T08:06:56+13:00 ERROR    : Error level log message
//     2017-11-16T08:06:56+13:00 CRITICAL : Critical level log message
//     2017-11-16T08:06:56+13:00 DEBUG    : You can see this message, because we changed level to DEBUG.
//     2017-11-16T08:06:56+13:00 TRACE(1) : Trace messages have their own numeric levels
//     2017-11-16T08:06:56+13:00 TRACE(1) : To see them set RLOG_TRACE_LEVEL to the cut-off number
//     2017-11-16T08:06:56+13:00 TRACE(1) : We're 1 levels down now...
//     2017-11-16T08:06:56+13:00 TRACE(2) : We're 2 levels down now...
//     2017-11-16T08:06:56+13:00 INFO     : Reached end of recursion at level 10
//     2017-11-16T08:06:56+13:00 INFO     : About to change log output. Check /tmp/rlog-output.log...
//     2017-11-16T08:06:56+13:00 INFO     : Back to stderr
//
// With time stamp, log level WARN, no trace logging (switched off by unsetting
// the variable), but with caller info ('23730' in the example below is the
// process ID):
//
//     $ export RLOG_CALLER_INFO=yes
//     $ export RLOG_LOG_LEVEL=WARN
//     $ export RLOG_TRACE_LEVEL=
//     $ go run examples/example.go
//
//     2017-11-16T08:07:57+13:00 WARN     : [21233 examples/example.go:31 (main.main)] Warning level log message
//     2017-11-16T08:07:57+13:00 ERROR    : [21233 examples/example.go:32 (main.main)] Error level log message
//     2017-11-16T08:07:57+13:00 CRITICAL : [21233 examples/example.go:33 (main.main)] Critical level log message
//     2017-11-16T08:07:57+13:00 DEBUG    : [21233 examples/example.go:42 (main.main)] You can see this message, because we changed level to DEBUG.
//     2017-11-16T08:07:57+13:00 INFO     : [21233 examples/example.go:17 (main.someRecursiveFunction)] Reached end of recursion at level 10
//     2017-11-16T08:07:57+13:00 INFO     : [21233 examples/example.go:52 (main.main)] About to change log output. Check /tmp/rlog-output.log...
//     2017-11-16T08:07:57+13:00 INFO     : [21233 examples/example.go:61 (main.main)] Back to stderr
//
// Without time stamp, no trace logging, no caller info:
//
//     $ export RLOG_LOG_NOTIME=yes
//     $ export RLOG_CALLER_INFO=no
//     $ go run examples/example.go
//
//     WARN     : Warning level log message
//     ERROR    : Error level log message
//     CRITICAL : Critical level log message
//     DEBUG    : You can see this message, because we changed level to DEBUG.
//     INFO     : Reached end of recursion at level 10
//     INFO     : About to change log output. Check /tmp/rlog-output.log...
//     INFO     : Back to stderr
//
// With time stamp in RFC822 format.
//
//     $ export RLOG_LOG_NOTIME=no
//     $ export RLOG_TIME_FORMAT=RFC822
//     $ go run examples/example.go
//
//     2017-11-16T08:08:49+13:00 WARN     : Warning level log message
//     2017-11-16T08:08:49+13:00 ERROR    : Error level log message
//     2017-11-16T08:08:49+13:00 CRITICAL : Critical level log message
//     2017-11-16T08:08:49+13:00 DEBUG    : You can see this message, because we changed level to DEBUG.
//     2017-11-16T08:08:49+13:00 INFO     : Reached end of recursion at level 10
//     2017-11-16T08:08:49+13:00 INFO     : About to change log output. Check /tmp/rlog-output.log...
//     2017-11-16T08:08:49+13:00 INFO     : Back to stderr
//
// With custom time stamp:
//
//     $ export RLOG_TIME_FORMAT="2006/01/06 15:04:05"
//     $ go run examples/example.go
//
//     2017-11-16T08:09:08+13:00 WARN     : Warning level log message
//     2017-11-16T08:09:08+13:00 ERROR    : Error level log message
//     2017-11-16T08:09:08+13:00 CRITICAL : Critical level log message
//     2017-11-16T08:09:08+13:00 DEBUG    : You can see this message, because we changed level to DEBUG.
//     2017-11-16T08:09:08+13:00 INFO     : Reached end of recursion at level 10
//     2017-11-16T08:09:08+13:00 INFO     : About to change log output. Check /tmp/rlog-output.log...
//     2017-11-16T08:09:08+13:00 INFO     : Back to stderr
//
//
//
//

package rlog