carb::logging::StandardLogger2

Defined in carb/logging/StandardLogger2.h

class StandardLogger2

A sub-interface of ILogging for StandardLogger instances.

Public Functions

virtual void addRef() = 0

Adds a reference to *this.

virtual void release() = 0

Releases a reference to *this.

When the last reference is released, *this is destroyed.

virtual Logger *getLogger() = 0

Retrieves access to the underlying Logger for *this.

See also

ILogging::addLogger() ILogging::removeLogger()

Returns

the underlying Logger.

virtual void setFilenameIncluded(bool included) = 0

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

A new instance will by default exclude this information.

Parameters

included – Whether the filename information should be included in the log message

virtual void setLineNumberIncluded(bool included) = 0

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

A new instance will by default exclude this information.

Parameters

included – Whether the line number information should be included in the log message

virtual void setFunctionNameIncluded(bool included) = 0

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

A new instance will by default exclude this information.

Parameters

included – Whether the function name information should be included in the log message

virtual void setTimestampIncluded(bool included) = 0

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.

Parameters

included – Whether the timestamp information should be included in the log message

virtual void setThreadIdIncluded(bool included) = 0

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

A new instance will by default exclude this information.

Parameters

included – Whether the thread id should be included in the log message

virtual void setSourceIncluded(bool included) = 0

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

A new instance will by default include this information.

Parameters

included – Whether the source (module) information should be included in the log message

virtual void setStandardStreamOutput(bool enabled) = 0

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.

Parameters

enabled – Whether log output should go to standard streams (stdout and stderr)

virtual void setDebugConsoleOutput(bool enabled) = 0

(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.

Parameters

enabled – Whether log output should be sent to the debug console.

virtual void setFileOutput(const char *filePath) = 0

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.

Parameters

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.

Returns

no return value.

virtual void setFileOuputFlushLevel(int32_t level) = 0

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.

Parameters

level – The starting log level to flush file log output at.

virtual void setFlushStandardStreamOutput(bool enabled) = 0

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.

Parameters

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.

virtual void setElapsedTimeUnits(const char *units) = 0

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.

Parameters

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.

virtual void setProcessIdIncluded(bool enabled) = 0

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

A new instance will by default exclude this information.

Parameters

enabled – Whether the process id should be included in the log message

virtual void setMultiProcessGroupId(int32_t id) = 0

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.

Parameters

id – [in] an arbitrary process group identifier to set.

virtual void setColorOutputIncluded(bool enabled) = 0

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.

Parameters

enabled – Whether log output should include color codes

virtual void setOutputStream(OutputStream outputStream) = 0

Specify the output stream that logging should go to.

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

Parameters

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.

virtual void setStandardStreamOutputLevelThreshold(int32_t level) = 0

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

Messages below this threshold will be dropped.

Parameters

level – The log level to set.

virtual void setDebugConsoleOutputLevelThreshold(int32_t level) = 0

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

Messages below this threshold will be dropped.

Parameters

level – The log level to set.

virtual void setFileOutputLevelThreshold(int32_t level) = 0

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

Messages below this threshold will be dropped.

Parameters

level – The log level to set.

virtual void setFileConfiguration(const char *filePath, const LogFileConfiguration *config) = 0

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.

Parameters

  • 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.

  • config – The LogFileConfiguration structure with parameters to use for the file configuration. Required.

virtual size_t getFileConfiguration(char *buffer, size_t bufferSize, LogFileConfiguration *config) = 0

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

Parameters

  • buffer – The buffer that will receive the UTF-8 file name that is being logged to. May be nullptr.

  • bufferSize – The maximum number of bytes available in buffer.

  • config – The LogFileConfiguration to receive the current configuration. May be nullptr.

Returns

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).

virtual void pauseFileLogging() = 0

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()

virtual void resumeFileLogging() = 0

Resumes file logging (potentially reopening the file)

Note

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

virtual void setForceAnsiColor(bool forceAnsiColor) = 0

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.

Parameters

forceAnsiColor – if true forces terminal to use ANSI escape codes for color

virtual void setLevelThresholdThreadOverride(OutputType type, int32_t level) = 0

Overrides the current log level, for the given stream, only for the calling thread.

Call clearLevelThresholdThreadOverride() to clear the override.

Parameters
virtual void clearLevelThresholdThreadOverride(OutputType type) = 0

Clears any override for the given stream, only for the calling thread.

The override was previously set with setLevelThresholdThreadOverride().

Parameters

type – The OutputType to override.

virtual LogDestinations getConfiguredLogDestinationsForLevel(int32_t level) = 0

Retrieves the current set of log destinations for this logger.

Parameters

level – [in] The logging level to check each destination against. This can be one of the standard kLevel* values. Each log destination that is currently enabled will only set its corresponding flag if the given log level is at or above the currently configured level for the same destination on the calling thread.

Returns

A set of flags indicating which log destinations are currently enabled for the given log level. Note that each destination can be affected by the configured logging level for the calling module and thread. Also note that since this check is performed separately from emitting any particular log message, there is a potential race between outputting a message then checking the destinations versus another thread changing the logger’s configuration. The returned values are more for informational purposes as a result.