Module io.jstach.rainbowgum

Package io.jstach.rainbowgum

Interface LogEvent

public sealed interface LogEvent

A LogEvent is a container for a single call to a logger. An event should not be created unless a route or logger is actually enabled.

Author:

agentgt

See Also:

• LogMessageFormatter

API Note

LogEvent is currently sealed. The reason there are so many static creation methods is for optimization purposes because other than actual outputting creating events is generally the most expensive operation (mostly in terms of memory) a logging system does.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	LogEvent.Builder	A builder to create events by calling LogRouter.eventBuilder(String, Level).
static interface	LogEvent.Caller	Caller info usually derived from Stack walking.

Method Summary

Modifier and Type	Method	Description
default @Nullable LogEvent.Caller	callerOrNull()	Returns info about caller or null if not supported.
void	formattedMessage(StringBuilder sb)	Appends the formatted message.
LogEvent	freeze()	Freeze will return a LogEvent that is safe to use in a different thread.
LogEvent	freeze(Instant timestamp)	Freeze and replace with the given timestamp.
KeyValues	keyValues()	Key values that usually come from MDC or an SLF4J Event Builder.
System.Logger.Level	level()	The logging level.
String	loggerName()	Name of logger.
String	message()	Unformatted message.
static LogEvent	of(System.Logger.Level level, String loggerName, String message, KeyValues keyValues, LogMessageFormatter messageFormatter, @Nullable Object arg1)	Creates a log event.
static LogEvent	of(System.Logger.Level level, String loggerName, String message, KeyValues keyValues, LogMessageFormatter messageFormatter, @Nullable Object arg1, @Nullable Object arg2)	Creates a log event.
static LogEvent	of(System.Logger.Level level, String loggerName, String formattedMessage, KeyValues keyValues, @Nullable Throwable throwable)	Creates a log event.
static LogEvent	of(System.Logger.Level level, String loggerName, String formattedMessage, @Nullable Throwable throwable)	Creates a log event.
static LogEvent	ofAll(Instant timestamp, String threadName, long threadId, System.Logger.Level level, String loggerName, String message, KeyValues keyValues, @Nullable Throwable throwable, LogMessageFormatter messageFormatter, @Nullable Object @Nullable [] args)	Creates a log event with everything specified.
static LogEvent	ofAll(Instant timestamp, String threadName, long threadId, System.Logger.Level level, String loggerName, String message, KeyValues keyValues, @Nullable Throwable throwable, LogMessageFormatter messageFormatter, @Nullable List<@Nullable Object> args)	Creates a log event with everything specified.
static LogEvent	ofArgs(System.Logger.Level level, String loggerName, String message, KeyValues keyValues, LogMessageFormatter messageFormatter, @Nullable Object[] args)	Creates a log event.
long	threadId()	Thread id.
String	threadName()	Name of the thread.
@Nullable Throwable	throwableOrNull()	Throwable at the time of the event passed from the logger.
Instant	timestamp()	Timestamp when the event was created.
static LogEvent	withCaller(LogEvent event, LogEvent.Caller caller)	Creates a new event with the caller info attached.

Method Details

of

static LogEvent of(System.Logger.Level level,
 String loggerName,
 String formattedMessage,
 KeyValues keyValues,
 @Nullable Throwable throwable)

Creates a log event.

Parameters:

level - the logging level.

loggerName - the name of the logger which is usually a class name.

formattedMessage - the unformatted message.

keyValues - key values that come from MDC or an SLF4J Event Builder.

throwable - an exception if passed maybe null.

Returns:

event

See Also:

• LevelResolver

API Note

the message is already assumed to be formatted as no arguments are passed.

of

static LogEvent of(System.Logger.Level level,
 String loggerName,
 String formattedMessage,
 @Nullable Throwable throwable)

Creates a log event.

Parameters:

level - the logging level.

loggerName - the name of the logger which is usually a class name.

formattedMessage - the unformatted message.

throwable - an exception if passed maybe null.

Returns:

event

See Also:

• LevelResolver

API Note

the message is already assumed to be formatted as no arguments are passed.

of

static LogEvent of(System.Logger.Level level,
 String loggerName,
 String message,
 KeyValues keyValues,
 LogMessageFormatter messageFormatter,
 @Nullable Object arg1)

Creates a log event.

Parameters:

level - the logging level.

loggerName - the name of the logger which is usually a class name.

message - the unformatted message.

keyValues - key values that come from MDC or an SLF4J Event Builder.

messageFormatter - formatter to use for rendering a message when #formattedMessage(StringBuilder) is called.

arg1 - argument that will be passed to messageFormatter.

Returns:

event

See Also:

• LevelResolver
• LogMessageFormatter

of

static LogEvent of(System.Logger.Level level,
 String loggerName,
 String message,
 KeyValues keyValues,
 LogMessageFormatter messageFormatter,
 @Nullable Object arg1,
 @Nullable Object arg2)

Creates a log event.

Parameters:

level - the logging level.

loggerName - the name of the logger which is usually a class name.

message - the unformatted message.

keyValues - key values that come from MDC or an SLF4J Event Builder.

messageFormatter - formatter to use for rendering a message when #formattedMessage(StringBuilder) is called.

arg1 - argument that will be passed to messageFormatter.

arg2 - argument that will be passed to messageFormatter.

Returns:

event

See Also:

• LevelResolver
• LogMessageFormatter

ofArgs

static LogEvent ofArgs(System.Logger.Level level,
 String loggerName,
 String message,
 KeyValues keyValues,
 LogMessageFormatter messageFormatter,
 @Nullable Object[] args)

Creates a log event.

Parameters:

level - the logging level.

loggerName - the name of the logger which is usually a class name.

message - the unformatted message.

keyValues - key values that come from MDC or an SLF4J Event Builder.

messageFormatter - formatter to use for rendering a message when #formattedMessage(StringBuilder) is called.

args - an array of arguments that will be passed to messageFormatter. The contents maybe null elements but the array itself should not be null.

Returns:

event

See Also:

• LevelResolver
• LogMessageFormatter

ofAll

static LogEvent ofAll(Instant timestamp,
 String threadName,
 long threadId,
 System.Logger.Level level,
 String loggerName,
 String message,
 KeyValues keyValues,
 @Nullable Throwable throwable,
 LogMessageFormatter messageFormatter,
 @Nullable List<@Nullable Object> args)

Creates a log event with everything specified.

Parameters:

timestamp - time of event

threadName - or empty string

threadId - thread id or 0 if that cannot be resolved.

level - the logging level.

loggerName - the name of the logger which is usually a class name.

message - the unformatted message.

keyValues - key values that come from MDC or an SLF4J Event Builder.

throwable - or null.

messageFormatter - formatter to use for rendering a message when #formattedMessage(StringBuilder) is called.

args - an array of arguments that will be passed to messageFormatter. The contents maybe null elements but the array itself should not be null.

Returns:

event

See Also:

• LevelResolver
• LogMessageFormatter

ofAll

static LogEvent ofAll(Instant timestamp,
 String threadName,
 long threadId,
 System.Logger.Level level,
 String loggerName,
 String message,
 KeyValues keyValues,
 @Nullable Throwable throwable,
 LogMessageFormatter messageFormatter,
 @Nullable Object @Nullable [] args)

Creates a log event with everything specified.

Parameters:

timestamp - time of event

threadName - or empty string

threadId - thread id or 0 if that cannot be resolved.

level - the logging level.

loggerName - the name of the logger which is usually a class name.

message - the unformatted message.

keyValues - key values that come from MDC or an SLF4J Event Builder.

throwable - or null.

messageFormatter - formatter to use for rendering a message when #formattedMessage(StringBuilder) is called.

args - an array of arguments that will be passed to messageFormatter. The contents maybe null elements but the array itself should not be null.

Returns:

event

See Also:

• LevelResolver
• LogMessageFormatter

withCaller

static LogEvent withCaller(LogEvent event,
 LogEvent.Caller caller)

Creates a new event with the caller info attached. This method always returns a new event does not check if the original has caller info.

Parameters:

event - original event.

caller - caller info.

Returns:

new log event.

timestamp

Instant timestamp()

Timestamp when the event was created.

Returns:

instant when the event was created.

threadName

String threadName()

Name of the thread.

Returns:

thread name.

API Note

this maybe empty and often is if virtual threads are used.

threadId

long threadId()

Thread id.

Returns:

thread id.

level

System.Logger.Level level()

The logging level. System.Logger.Level.ALL and System.Logger.Level.OFF should not be returned as they have special meaning.

Returns:

level.

loggerName

String loggerName()

Name of logger.

Returns:

name of logger.

message

String message()

Unformatted message.

Returns:

unformatted message

See Also:

• formattedMessage(StringBuilder)

formattedMessage

void formattedMessage(StringBuilder sb)

Appends the formatted message.

Parameters:

sb - string builder to use.

See Also:

• LogMessageFormatter

throwableOrNull

@Nullable Throwable throwableOrNull()

Throwable at the time of the event passed from the logger.

Returns:

if the event does not have a throwable null will be returned.

keyValues

KeyValues keyValues()

Key values that usually come from MDC or an SLF4J Event Builder.

Returns:

key values.

callerOrNull

default @Nullable LogEvent.Caller callerOrNull()

Returns info about caller or null if not supported.

Returns:

caller info

freeze

LogEvent freeze()

Freeze will return a LogEvent that is safe to use in a different thread. Usually this entails copying the data or checking if it is already immutable. Freeze should be called before passing an event to an LogPublisher.AsyncLogPublisher.

Returns:

thread safe log event.

freeze

LogEvent freeze(Instant timestamp)

Freeze and replace with the given timestamp.

Parameters:

timestamp - instant to replace timestamp in this.

Returns:

a copy of this with the given timestamp.