Interface LogEvent
-
- All Superinterfaces:
Serializable
- All Known Implementing Classes:
AbstractLogEvent
,Log4jLogEvent
,LogEventWrapper
,MutableLogEvent
,RingBufferLogEvent
public interface LogEvent extends Serializable
Provides contextual information about a logged message. A LogEvent must beSerializable
so that it may be transmitted over a network connection, output in aSerializedLayout
, and many other uses. Besides containing aMessage
, a LogEvent has a correspondingLevel
that the message was logged at. If aMarker
was used, then it is included here. The contents of theThreadContext
at the time of the log call are provided viagetContextMap()
andgetContextStack()
. If aThrowable
was included in the log call, then it is provided viagetThrown()
. When this class is serialized, the attached Throwable will be wrapped into aThrowableProxy
so that it may be safely serialized and deserialized properly without causing problems if the exception class is not available on the other end.Since version 2.7,
getContextMap()
is deprecated in favor ofgetContextData()
, which can carry bothThreadContext
data as well as other context data supplied by the configuredContextDataInjector
.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description ReadOnlyStringMap
getContextData()
Returns theReadOnlyStringMap
object holding context data key-value pairs.Map<String,String>
getContextMap()
Deprecated.usegetContextData()
insteadThreadContext.ContextStack
getContextStack()
Gets the context stack (also known as Nested Diagnostic Context or NDC).Instant
getInstant()
Returns the Instant when the message was logged.Level
getLevel()
Gets the level.String
getLoggerFqcn()
Returns the fully qualified class name of the caller of the logging API.String
getLoggerName()
Gets the logger name.Marker
getMarker()
Gets the Marker associated with the event.Message
getMessage()
Gets the message associated with the event.long
getNanoTime()
Returns the value of the running Java Virtual Machine's high-resolution time source when this event was created, or a dummy value if it is known that this value will not be used downstream.StackTraceElement
getSource()
Gets the source of logging request.long
getThreadId()
Gets the thread ID.String
getThreadName()
Gets the thread name.int
getThreadPriority()
Gets the thread priority.Throwable
getThrown()
Gets throwable associated with logging request.ThrowableProxy
getThrownProxy()
Gets throwable proxy associated with logging request.long
getTimeMillis()
Gets event time in milliseconds since midnight, January 1, 1970 UTC.boolean
isEndOfBatch()
Returnstrue
if this event is the last one in a batch,false
otherwise.boolean
isIncludeLocation()
Returns whether the source of the logging request is required downstream.void
setEndOfBatch(boolean endOfBatch)
Sets whether this event is the last one in a batch.void
setIncludeLocation(boolean locationRequired)
Sets whether the source of the logging request is required downstream.LogEvent
toImmutable()
Returns an immutable version of this log event, which MAY BE a copy of this event.
-
-
-
Method Detail
-
toImmutable
LogEvent toImmutable()
Returns an immutable version of this log event, which MAY BE a copy of this event.- Returns:
- an immutable version of this log event
-
getContextMap
@Deprecated Map<String,String> getContextMap()
Deprecated.usegetContextData()
insteadGets the context map (also know as Mapped Diagnostic Context or MDC).- Returns:
- The context map, never
null
.
-
getContextData
ReadOnlyStringMap getContextData()
Returns theReadOnlyStringMap
object holding context data key-value pairs.Context data (also known as Mapped Diagnostic Context or MDC) is data that is set by the application to be included in all subsequent log events. The default source for context data is the
ThreadContext
(and properties configured on the Logger that logged the event), but users can configure a customContextDataInjector
to inject key-value pairs from any arbitrary source.- Returns:
- the
ReadOnlyStringMap
object holding context data key-value pairs - Since:
- 2.7
- See Also:
ContextDataInjector
,ThreadContext
-
getContextStack
ThreadContext.ContextStack getContextStack()
Gets the context stack (also known as Nested Diagnostic Context or NDC).- Returns:
- The context stack, never
null
.
-
getLoggerFqcn
String getLoggerFqcn()
Returns the fully qualified class name of the caller of the logging API.- Returns:
- The fully qualified class name of the caller.
-
getLevel
Level getLevel()
Gets the level.- Returns:
- level.
-
getLoggerName
String getLoggerName()
Gets the logger name.- Returns:
- logger name, may be
null
.
-
getMarker
Marker getMarker()
Gets the Marker associated with the event.- Returns:
- Marker or
null
if no Marker was defined on this LogEvent
-
getMessage
Message getMessage()
Gets the message associated with the event.- Returns:
- message.
-
getTimeMillis
long getTimeMillis()
Gets event time in milliseconds since midnight, January 1, 1970 UTC. UsegetInstant()
to get higher precision timestamp information if available on this platform.- Returns:
- the milliseconds component of this log event's timestamp
- See Also:
System.currentTimeMillis()
-
getInstant
Instant getInstant()
Returns the Instant when the message was logged.Caution: if this
LogEvent
implementation is mutable and reused for multiple consecutive log messages, then theInstant
object returned by this method is also mutable and reused. Client code should not keep a reference to the returned object but make a copy instead.- Returns:
- the
Instant
holding Instant details for this log event - Since:
- 2.11
-
getSource
StackTraceElement getSource()
Gets the source of logging request.- Returns:
- source of logging request, may be null.
-
getThreadName
String getThreadName()
Gets the thread name.- Returns:
- thread name, may be null. TODO guess this could go into a thread context object too. (RG) Why?
-
getThreadId
long getThreadId()
Gets the thread ID.- Returns:
- thread ID.
- Since:
- 2.6
-
getThreadPriority
int getThreadPriority()
Gets the thread priority.- Returns:
- thread priority.
- Since:
- 2.6
-
getThrown
Throwable getThrown()
Gets throwable associated with logging request.Convenience method for
ThrowableProxy.getThrowable();
- Returns:
- throwable, may be null.
-
getThrownProxy
ThrowableProxy getThrownProxy()
Gets throwable proxy associated with logging request.- Returns:
- throwable, may be null.
-
isEndOfBatch
boolean isEndOfBatch()
Returnstrue
if this event is the last one in a batch,false
otherwise. Used by asynchronous Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient alternative to theimmediateFlush=true
configuration.- Returns:
- whether this event is the last one in a batch.
-
isIncludeLocation
boolean isIncludeLocation()
Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use this flag to determine whether to take aStackTrace
snapshot or not before handing off this event to another thread.- Returns:
true
if the source of the logging request is required downstream,false
otherwise.- See Also:
getSource()
-
setEndOfBatch
void setEndOfBatch(boolean endOfBatch)
Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient alternative to theimmediateFlush=true
configuration.- Parameters:
endOfBatch
-true
if this event is the last one in a batch,false
otherwise.
-
setIncludeLocation
void setIncludeLocation(boolean locationRequired)
Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use this flag to determine whether to take aStackTrace
snapshot or not before handing off this event to another thread.- Parameters:
locationRequired
-true
if the source of the logging request is required downstream,false
otherwise.- See Also:
getSource()
-
getNanoTime
long getNanoTime()
Returns the value of the running Java Virtual Machine's high-resolution time source when this event was created, or a dummy value if it is known that this value will not be used downstream.- Returns:
- The value of the running Java Virtual Machine's high-resolution time source when this event was created.
- Since:
- Log4J 2.4
-
-