carb::logging::StandardLogger

Defined in carb/logging/StandardLogger.h

struct StandardLogger : public carb::logging::Logger 

The default logger provided by the Framework.

It is quite flexible and you can use multiple instances if you want different configurations for different output destinations. It can also be safely called from multiple threads.

See also

ILogging::destroyStandardLogger

Public Members

void (*setFilenameIncluded)(StandardLogger *instance, bool included)

Includes or excludes the filename of where the log message came from.

A new instance will by default exclude this information.

Param included: Whether the filename information should be included in the log message
Param instance: The instance of the StandardLogger interface being used. May not be nullptr. May not be nullptr.

void (*setLineNumberIncluded)(StandardLogger *instance, bool included)

Includes or excludes the line number of where the log message came from.

A new instance will by default exclude this information.

Param included: Whether the line number information should be included in the log message
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setFunctionNameIncluded)(StandardLogger *instance, bool included)

Includes or excludes the function name of where the log message came from.

A new instance will by default exclude this information.

Param included: Whether the function name information should be included in the log message
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setTimestampIncluded)(StandardLogger *instance, bool included)

Includes or excludes the timestamp of when the log message was issued.

A new instance will by default exclude this information. The time is in UTC format.

Param included: Whether the timestamp information should be included in the log message
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setThreadIdIncluded)(StandardLogger *instance, bool included)

Includes or excludes the id of a thread from which the log message was issued.

A new instance will by default exclude this information.

Param included: Whether the thread id should be included in the log message
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setSourceIncluded)(StandardLogger *instance, bool included)

Includes or excludes the source (module) of where the log message came from.

A new instance will by default include this information.

Param included: Whether the source (module) information should be included in the log message
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setStandardStreamOutput)(StandardLogger *instance, bool enabled)

Enables (or disables) standard stream output (stdout and stderr) for the logger.

Error messages are written to stderr, all other messages to stdout. A new FrameworkLogger will have this output enabled.

Param enabled: Whether log output should go to standard streams (stdout and stderr)
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setDebugConsoleOutput)(StandardLogger *instance, bool enabled)

(Windows only) Enables (or disables) debug console output for the logger via OutputDebugStringW().

By default, debug output is only supplied if a debugger is attached (via IsDebuggerPresent()). Calling this with enabled as true will always produce debug output which is useful for non-debugger tools such as SysInternals DebugView.

Param enabled: Whether log output should be sent to the debug console.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setFileOutput)(StandardLogger *instance, const char *filePath)

sets the path to the log file to open.

Remark

This sets the path to the log file to write to for the given instance of a standard logger object. The log file name may contain the string “${pid}” to have the process ID inserted in its place. By default, a new standard logger will disable logging to a file.

Note

Setting the log file name with this function will preserve the previous log file configuration. If the configuration needs to changes as well (ie: change the ‘append’ state of the log file), setFileConfiguration() should be used instead.

Param filePath: [in] the local file path to write the log file to. This may be a relative or absolute path. Relative paths will be resolved relative to the process’s current working directory at the time of the call. This may be nullptr to not write to a log file at all or to close the current log file. If a log file was previously open during this call, it will be closed first. If nullptr is passed in here, logging to a file will effectively be disabled. This path must be UTF-8 encoded. See the remarks below for more information on formatting of the log file path.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.
Return: no return value.

void (*setFileOuputFlushLevel)(StandardLogger *instance, int32_t level)

Enables flushing on every log message to file specified severity or higher.

A new instance will have this set to flush starting from kLevelVerbose, so that file logging will be reliable out of the box. The idea is that file logging will be used for debugging purposes by default, with a price of significant performance penalty.

Param level: The starting log level to flush file log output at.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setFlushStandardStreamOutput)(StandardLogger *instance, bool enabled)

Enables flushing of stdout after each message is printed to it.

By default, this option will be disabled. The default behavior will be to only flush stdout just before writing a message to stderr.

Param enabled: Set to true to cause stdout to be flushed after each message is written. Set to false to use the default behavior of only flushing stdout before writing to stderr.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setElapsedTimeUnits)(StandardLogger *instance, const char *units)

Enables a high resolution time index to be printed with each message.

By default, this option is disabled (ie: no time index printed). When enabled, the current time index (since the first message was printed) will be printed with each message. The time index may be in milliseconds, microseconds, or nanoseconds depending on the string units. The printing of the time index may be enabled at the same time as the timestamp.

Param units

[in] the units that the time index should be printed in. This can be one of the following supported unit names:

nullptr, “”, or “none”: the time index printing is disabled (default state).
”ms”, “milli”, or “milliseconds”: print the time index in milliseconds.
”us”, “µs”, “micro”, or “microseconds”: print the time index in microseconds.
”ns”, “nano”, or “nanoseconds”: print the time index in nanoseconds.

Param instance

The instance of the StandardLogger interface being used. May not be nullptr.

void (*setProcessIdIncluded)(StandardLogger *instance, bool enabled)

Includes or excludes the id of the process from which the log message was issued.

A new instance will by default exclude this information.

Param enabled: Whether the process id should be included in the log message
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setMultiProcessGroupId)(StandardLogger *instance, int32_t id)

sets the process group ID for the logger.

If a non-zero identifier is given, inter-process locking will be enabled on both the log file and the stdout/stderr streams. This will prevent simultaneous messages from multiple processes in the logs from becoming interleaved within each other. If a zero identifier is given, inter-process locking will be disabled.

Param id: [in] an arbitrary process group identifier to set.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setColorOutputIncluded)(StandardLogger *instance, bool enabled)

Enables (or disables) color codes output for the logger.

A new instance will have this output enabled unless the output is piped to a file, in which case this will be disabled.

Param enabled: Whether log output should include color codes
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setOutputStream)(StandardLogger *instance, OutputStream outputStream)

Specify the output stream that logging should go to.

By default, messages are sent to stdout and errors are sent to stderr.

Param outputStream: [in] The output stream setting to use. If this is OutputStream::eStderr, all logging output will be sent to stderr. If this is OutputStream::eDefault, the default logging behavior will be used.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setStandardStreamOutputLevelThreshold)(StandardLogger *instance, int32_t level)

Sets the log level threshold for the messages going to the standard stream.

Messages below this threshold will be dropped.

Param level: The log level to set.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setDebugConsoleOutputLevelThreshold)(StandardLogger *instance, int32_t level)

Sets the log level threshold for the messages going to the debug console output.

Messages below this threshold will be dropped.

Param level: The log level to set.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setFileOutputLevelThreshold)(StandardLogger *instance, int32_t level)

Sets the log level threshold for the messages going to the file output.

Messages below this threshold will be dropped.

Param level: The log level to set.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setFileConfiguration)(StandardLogger *instance, const char *filePath, const LogFileConfiguration *config)

Sets the file path and configuration for file logging.

If nullptr is provided the file logging is disabled. A new instance will by default disable file output.

Param filePath: The local file path to write to or nullptr, if you want to disable logging to file. Parameter is encoded as UTF8 character string with forward slashes as path separator. The path should include the extension .log but this is not a requirement. If a relative path is provided it is interpreted to be relative to the current working directory for the application. Can be kKeepSameFile to keep logging to the same file but set a new LogFileConfiguration.
Param config: The LogFileConfiguration structure with parameters to use for the file configuration. Required.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

size_t (*getFileConfiguration)(StandardLogger *instance, char *buffer, size_t bufferSize, LogFileConfiguration *config)

Returns the file path (in buffer) and configuration for file logging.

Param buffer: The buffer that will receive the UTF-8 file name that is being logged to. May be nullptr.
Param bufferSize: The maximum number of bytes available in buffer.
Param config: The LogFileConfiguration to receive the current configuration. May be nullptr.
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.
Return: If successful, the number of non-NUL bytes written to buffer. If not successful, contains the required size of a buffer to receive the filename (not including the NUL terminator).

void (*pauseFileLogging)(StandardLogger *instance)

Pauses file logging (and closes the file) until resumeFileLogging() is called.

Note

This is a counted call. Each call to pauseFileLogging() must have a matching call to resumeFileLogging()

Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*resumeFileLogging)(StandardLogger *instance)

Resumes file logging (potentially reopening the file)

Note

This is a counted call. Each call to pauseFileLogging() must have a matching call to resumeFileLogging()

Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*setForceAnsiColor)(StandardLogger *instance, bool forceAnsiColor)

Forces the logger to use ANSI escape code’s to annotate the log with color.

By default, on Windows ANSI escape codes will never be used, rather the Console API will be used to place colors in a console. Linux uses the isatty() to determine if the terminal supports ANSI escape codes. However, the isatty check doesn’t work in all cases. One notable case where this doesn’t work is running a process in a CI/CD that returns false from isatty() yet still supports ANSI escape codes.

See: https://en.wikipedia.org/wiki/ANSI_escape_code for more information about ANSI escape codes.

Param forceAnsiColor: if true forces terminal to use ANSI escape codes for color
Param instance: The instance of the StandardLogger interface being used. May not be nullptr.

void (*handleMessage)(Logger *logger, const char *source, int32_t level, const char *filename, const char *functionName, int lineNumber, const char *message)

Handler for a formatted log message.

This function is called by ILogging if the Logger has been registered via ILogging::addLogger(), log level passes the threshold (for module or globally if not set for module), and logging is enabled (for module or globally if not set for module).

Thread Safety: this function will potentially be called simultaneously from multiple threads. The thread that calls this function is not necessarily the thread that originated the log message, such as in the case of asynchronous logging.

Note

As of 161.0 the Framework protects against recursively calling a Logger in the event that a Logger performs an action that would recursively log. In these situations, the offending Logger will not receive the recursive log message, but other Loggers will receive it.

Note

In some cases such as when certain mutexes are locked, log messages are deferred by the Framework in order to prevent Logger objects from calling back into the Framework on the thread that has the mutex locked.

Param logger: The logger interface - can be nullptr if not used by handleMessage
Param source: The source of the message in UTF8 character encoding - commonly plugin name
Param level: The severity level of the message
Param filename: The file name where the message originated from.
Param functionName: The name of the function where the message originated from.
Param lineNumber: The line number where the message originated from
Param message: The formatted message in UTF8 character encoding