core/com.tealium.prism.core.api.logger/Logger

Logger

interface Logger

A central utility class for processing log statements at various log levels.

Log messages are not guaranteed to be processed immediately upon calling one of the logging methods, however they will be processed in the order that they are received.

It is preferable to avoid unnecessary code execution when writing log statements. For example, try not to pre-calculate complicated log messages before passing them into the log methods, in case the LogLevel is not sufficiently set for it to actually be logged. As such there are several methods available to support efficient logging, some of which will delay evaluation of the message:

With a simple String input - this is preferred for simple cases where a pre-determined String input is used and no complicated processing would occur outside of the String allocation

logger.trace("category", "Simple message")

With String.format and varargs - this is typically useful for cases where a small number of arguments are to be formatted into the log message, but the calculation of any of the arguments' toString method is non-trivial. e.g. formatting a complex object as a JSON string. Therefore, this approach is also not preferred if the args will need to be manipulated in some way before passing to the log method, or where large lists of args make the statement difficult to read.

// good
logger.trace("category", "Color: %s", "red") // Color: red
logger.trace("category", "$%.2f", money) // $10.55

// less good
logger.trace("category", "JSON: %s", jsonObject.toJsonString())
logger.trace("category", "%s, %s, %s, %s, %s, %s, %s,",
     arg1, arg2, arg3, arg4, arg5, arg6, arg7,
)

With a message supplier - this is typically useful for cases where it would be more readable to build the message in a block, but the calculation of the message would benefit from being evaluated later.

logger.trace("category") {
     jsonObject.toJsonString()
}

Note. For Kotlin call sites, there are also inline extension methods available that will inline a check that the logger is configured with the required level of logging, before calling the respective method on the logger. This allows the caller to sidestep any complicated message processing whilst also avoiding extra anonymous classes. For instance, the following are equivalent:

if (logger.shouldLog(LogLevel.TRACE) {
     logger.trace("category", jsonObject.toJsonString())
}

// or inlined:
logger.logIfTraceEnabled("category") {
     jsonObject.toJsonString()
}

Most Kotlin call-sites should prefer these extension methods for readability and efficiency, but for cases at the very start of SDK initialization, where no LogLevel has been set yet, the implicit shouldLog check will always return true causing the log message to be eagerly evaluated.

Java call-sites, where inlining is not available, can choose whichever method is more appropriate/readable.

Properties

isDebugLogging

val Logger.isDebugLogging: Boolean

Convenience method to check that the log level is set to debug or higher

isErrorLogging

val Logger.isErrorLogging: Boolean

Convenience method to check that the log level is set to error or higher

isInfoLogging

val Logger.isInfoLogging: Boolean

Convenience method to check that the log level is set to info or higher

isTraceLogging

val Logger.isTraceLogging: Boolean

Convenience method to check that the log level is set to trace or higher

isWarnLogging

val Logger.isWarnLogging: Boolean

Convenience method to check that the log level is set to warn or higher

Functions

debug

abstract fun debug(category: String, message: () -> String)

Logs a LogLevel.DEBUG level message with the given category by evaluating the log message from the given message

abstract fun debug(category: String, message: String)

Logs a LogLevel.TRACE level message with the given category.

abstract fun debug(category: String, message: String, vararg args: Any?)

Logs a LogLevel.DEBUG level message with the given category by formatting the message using String.format, inserting the args into the placeholders in the order given in the message

error

abstract fun error(category: String, message: () -> String)

Logs a LogLevel.INFO level message with the given category by evaluating the log message from the given message

abstract fun error(category: String, message: String)

Logs a LogLevel.TRACE level message with the given category.

abstract fun error(category: String, message: String, vararg args: Any?)

Logs a LogLevel.ERROR level message with the given category by formatting the message using String.format, inserting the args into the placeholders in the order given in the message

info

abstract fun info(category: String, message: () -> String)

Logs a LogLevel.INFO level message with the given category by evaluating the log message from the given message

abstract fun info(category: String, message: String)

Logs a LogLevel.TRACE level message with the given category.

abstract fun info(category: String, message: String, vararg args: Any?)

Logs a LogLevel.INFO level message with the given category by formatting the message using String.format, inserting the args into the placeholders in the order given in the message

log

abstract fun log(level: LogLevel, category: String, message: () -> String)

Logs a message at the given level and category by evaluating the log message from the given message

abstract fun log(level: LogLevel, category: String, message: String)

Logs a message at the given level and category.

abstract fun log(level: LogLevel, category: String, message: String, vararg args: Any?)

Logs a message at the given level and category by formatting the message using String.format, inserting the args into the placeholders in the order given in the message

logIfDebugEnabled

inline fun Logger.logIfDebugEnabled(category: String, message: () -> String)

Inlines a check for whether the Logger is currently logging at LogLevel.DEBUG, before evaluating the message, whilst avoiding an unnecessary anonymous class implementation.

logIfErrorEnabled

inline fun Logger.logIfErrorEnabled(category: String, message: () -> String)

Inlines a check for whether the Logger is currently logging at LogLevel.ERROR, before evaluating the message, whilst avoiding an unnecessary anonymous class implementation.

logIfInfoEnabled

inline fun Logger.logIfInfoEnabled(category: String, message: () -> String)

Inlines a check for whether the Logger is currently logging at LogLevel.INFO, before evaluating the message, whilst avoiding an unnecessary anonymous class implementation.

logIfTraceEnabled

inline fun Logger.logIfTraceEnabled(category: String, message: () -> String)

Inlines a check for whether the Logger is currently logging at LogLevel.TRACE, before evaluating the message, whilst avoiding an unnecessary anonymous class implementation.

logIfWarnEnabled

inline fun Logger.logIfWarnEnabled(category: String, message: () -> String)

Inlines a check for whether the Logger is currently logging at LogLevel.WARN, before evaluating the message, whilst avoiding an unnecessary anonymous class implementation.

shouldLog

abstract fun shouldLog(level: LogLevel): Boolean

Returns whether or not the given level should be logged by the currently configured LogLevel.

trace

abstract fun trace(category: String, message: () -> String)

Logs a LogLevel.TRACE level message with the given category by evaluating the log message from the given message

abstract fun trace(category: String, message: String)

Logs a LogLevel.TRACE level message with the given category.

abstract fun trace(category: String, message: String, vararg args: Any?)

Logs a LogLevel.TRACE level message with the given category by formatting the message using String.format, inserting the args into the placeholders in the order given in the message

warn

abstract fun warn(category: String, message: () -> String)

Logs a LogLevel.WARN level message with the given category by evaluating the log message from the given message

abstract fun warn(category: String, message: String)

Logs a LogLevel.TRACE level message with the given category.

abstract fun warn(category: String, message: String, vararg args: Any?)

Logs a LogLevel.WARN level message with the given category by formatting the message using String.format, inserting the args into the placeholders in the order given in the message

Logger

See also

Properties

Functions