Log levels, in increasing severity/precedence order.

A log event.

Can be converted to a string later, or thrown away.

Request a CallStack.

NOTE: The implicit parameter ?callStack :: CallStack is an implementation detail and should not be considered part of the CallStack API, we may decide to change the implementation in the future.

Since: base-4.9.0.0

Access to the log config.

Users should prefer withLogCfg to binding the implicit param. The implicit param is an implementation detail, and we could change the implementation later, e.g. to use the reflection package.

We use an implicit param to avoid having to change all code in IO that wants to log to be in MonadHasLogCfg and MonadIO classes.

An even more convenient but more "unsafe" implementation would store the LogCfg in a global, unsafePerformIOd IORef (cf. uniqueSource in Unique).

Log in a MonadIO.

If you want the name of function that called log to be included in the output, then you need to add a HasCallStack constraint to it as well (see LogC). Otherwise, one of two things will happen:

• if no enclosing function has a HasCallStack constraint, then ??? will be used for the enclosing function name.
• if at least one enclosing function has a HasCallStack constraint, then the name of the *closest* enclosing function with that constraint will be used for the enclosing function name. So, for example, if you define outer by

outer :: (MonadHasLogCfg m, Ghc.HasCallStack) => m Int
outer = inner
  where
    inner = do
      log Debug "Inside 'inner' ..."
      return 42

then the call to log in inner will have "outer" as the enclosing function name.

Log in pure code using unsafePerformIO, like Trace.

See logIO.

Satisfy a HasLogCfg constraint.

Users can call this function instead of using ImplicitParams themselves.

Recover the log config.

Useful for going between implicit and monadic interfaces. E.g.

flip runReaderT getLogCfg ...

logIO with an explicit config

Signal to the log consumer that there are no more log messages and terminate the log consumer. This is useful for cases where the logger is running in a separate thread and the parent thread wants to wait until the logger has finished logging and has successfully flushed all log messages before terminating it.

Write a LogEvent to the underlying channel.

This is a low-level function. See logIO, logM, and logTrace for a high-level interface that supplies the LogCfg and CallStack parameters automatically.

However, those functions can't be used to build up custom loggers, since they infer call stack information automatically. If you want to define a custom logger (even something simple like

debug msg = logM Debug msg

) then use writeLogEvent.

Monads with logger configuration.

Log in a MonadHasLogCfg.

See logIO.

Logging configuration.

Initialize a LogCfg.

The first argument is the human friendly name to assign to the current thread. Since logging should be configured as soon as possible on startup, "main" is probably the right name.

See asyncNamed for naming other threads.

Need to start a log event consumer in another thread, e.g. stdErrLogEventConsumer, if you want anything to happen with the log events.

Initialize a LogCfg that does no logging.

This can be used as a LogCfg when no logging is to be performed. Runtime overhead is smaller when this configuration is specified at compile time.

Run an action with the given log event consumer.

In particular this provides an easy way to run one-off computations that assume logging, e.g. in GHCi. Spawns the log even consumer before running the action and cleans up the log event consumer afterwards.

A log event consumer that prints formatted log events to stderr.

A logger that writes to a user-specified file

Note that logs are opened in the w mode (i.e., overwrite). Callers should preserve old log files if they really want.

A log event consumer that writes formatted log events to a tmp file.

Format a log event.

Consume a log channel until it receives a shutdown message (i.e. a Nothing).

Only messages that satisfy the predicate will be passed to the continuation. For example, using const True will process all log messages, and using (>= Info) . leLevel will only process messsages with LogLevel equal to Info or higher, ignoring Debug level messages.

Run an IO action with a human friendly thread name.

Any existing thread name will be restored when the action finishes.

Version of named for implicit log cfg.

Version of named for MonadHasLogCfg monads.