1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache license, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the license for the specific language governing permissions and
15 * limitations under the license.
16 */
17
18 package org.apache.logging.log4j.core;
19
20 import java.io.Serializable;
21 import java.util.Map;
22
23 import org.apache.logging.log4j.Level;
24 import org.apache.logging.log4j.Marker;
25 import org.apache.logging.log4j.ThreadContext;
26 import org.apache.logging.log4j.core.impl.ThrowableProxy;
27 import org.apache.logging.log4j.core.time.Instant;
28 import org.apache.logging.log4j.message.Message;
29 import org.apache.logging.log4j.util.ReadOnlyStringMap;
30
31 /**
32 * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
33 * may be transmitted over a network connection, output in a
34 * {@link org.apache.logging.log4j.core.layout.SerializedLayout}, and many other uses. Besides containing a
35 * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
36 * {@link org.apache.logging.log4j.Level} that the message was logged at. If a
37 * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
38 * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
39 * {@link #getContextMap()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
40 * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
41 * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
42 * and deserialized properly without causing problems if the exception class is not available on the other end.
43 * <p>
44 * Since version 2.7, {@link #getContextMap()} is deprecated in favor of {@link #getContextData()}, which
45 * can carry both {@code ThreadContext} data as well as other context data supplied by the
46 * {@linkplain org.apache.logging.log4j.core.impl.ContextDataInjectorFactory configured}
47 * {@link ContextDataInjector}.
48 * </p>
49 */
50 public interface LogEvent extends Serializable {
51
52 /**
53 * Returns an immutable version of this log event, which MAY BE a copy of this event.
54 *
55 * @return an immutable version of this log event
56 */
57 LogEvent toImmutable();
58
59 /**
60 * Gets the context map (also know as Mapped Diagnostic Context or MDC).
61 *
62 * @return The context map, never {@code null}.
63 * @deprecated use {@link #getContextData()} instead
64 */
65 @Deprecated
66 Map<String, String> getContextMap();
67
68 /**
69 * Returns the {@code ReadOnlyStringMap} object holding context data key-value pairs.
70 * <p>
71 * Context data (also known as Mapped Diagnostic Context or MDC) is data that is set by the application to be
72 * included in all subsequent log events. The default source for context data is the {@link ThreadContext} (and
73 * <a href="https://logging.apache.org/log4j/2.x/manual/configuration.html#PropertySubstitution">properties</a>
74 * configured on the Logger that logged the event), but users can configure a custom {@link ContextDataInjector}
75 * to inject key-value pairs from any arbitrary source.
76 *
77 * @return the {@code ReadOnlyStringMap} object holding context data key-value pairs
78 * @see ContextDataInjector
79 * @see ThreadContext
80 * @since 2.7
81 */
82 ReadOnlyStringMap getContextData();
83
84 /**
85 * Gets the context stack (also known as Nested Diagnostic Context or NDC).
86 *
87 * @return The context stack, never {@code null}.
88 */
89 ThreadContext.ContextStack getContextStack();
90
91 /**
92 * Returns the fully qualified class name of the caller of the logging API.
93 *
94 * @return The fully qualified class name of the caller.
95 */
96 String getLoggerFqcn();
97
98 /**
99 * Gets the level.
100 *
101 * @return level.
102 */
103 Level getLevel();
104
105 /**
106 * Gets the logger name.
107 *
108 * @return logger name, may be {@code null}.
109 */
110 String getLoggerName();
111
112 /**
113 * Gets the Marker associated with the event.
114 *
115 * @return Marker or {@code null} if no Marker was defined on this LogEvent
116 */
117 Marker getMarker();
118
119 /**
120 * Gets the message associated with the event.
121 *
122 * @return message.
123 */
124 Message getMessage();
125
126 /**
127 * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
128 * Use {@link #getInstant()} to get higher precision timestamp information if available on this platform.
129 *
130 * @return the milliseconds component of this log event's {@linkplain #getInstant() timestamp}
131 * @see java.lang.System#currentTimeMillis()
132 */
133 long getTimeMillis();
134
135 /**
136 * Returns the Instant when the message was logged.
137 * <p>
138 * <b>Caution</b>: if this {@code LogEvent} implementation is mutable and reused for multiple consecutive log messages,
139 * then the {@code Instant} object returned by this method is also mutable and reused.
140 * Client code should not keep a reference to the returned object but make a copy instead.
141 * </p>
142 *
143 * @return the {@code Instant} holding Instant details for this log event
144 * @since 2.11
145 */
146 Instant getInstant();
147
148 /**
149 * Gets the source of logging request.
150 *
151 * @return source of logging request, may be null.
152 */
153 StackTraceElement getSource();
154
155 /**
156 * Gets the thread name.
157 *
158 * @return thread name, may be null.
159 * TODO guess this could go into a thread context object too. (RG) Why?
160 */
161 String getThreadName();
162
163 /**
164 * Gets the thread ID.
165 *
166 * @return thread ID.
167 * @since 2.6
168 */
169 long getThreadId();
170
171 /**
172 * Gets the thread priority.
173 *
174 * @return thread priority.
175 * @since 2.6
176 */
177 int getThreadPriority();
178
179 /**
180 * Gets throwable associated with logging request.
181 *
182 * <p>Convenience method for {@code ThrowableProxy.getThrowable();}</p>
183 *
184 * @return throwable, may be null.
185 */
186 Throwable getThrown();
187
188 /**
189 * Gets throwable proxy associated with logging request.
190 *
191 * @return throwable, may be null.
192 */
193 ThrowableProxy getThrownProxy();
194
195 /**
196 * Returns {@code true} if this event is the last one in a batch, {@code false} otherwise. Used by asynchronous
197 * Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient
198 * alternative to the {@code immediateFlush=true} configuration.
199 *
200 * @return whether this event is the last one in a batch.
201 */
202 // see also LOG4J2-164
203 boolean isEndOfBatch();
204
205 /**
206 * Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
207 * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
208 * another thread.
209 *
210 * @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
211 * @see #getSource()
212 */
213 // see also LOG4J2-153
214 boolean isIncludeLocation();
215
216 /**
217 * Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to
218 * buffered downstream components when to flush to disk, as a more efficient alternative to the
219 * {@code immediateFlush=true} configuration.
220 *
221 * @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
222 */
223 void setEndOfBatch(boolean endOfBatch);
224
225 /**
226 * Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
227 * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
228 * another thread.
229 *
230 * @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false}
231 * otherwise.
232 * @see #getSource()
233 */
234 void setIncludeLocation(boolean locationRequired);
235
236 /**
237 * Returns the value of the running Java Virtual Machine's high-resolution time source when this event was created,
238 * or a dummy value if it is known that this value will not be used downstream.
239 * @return The value of the running Java Virtual Machine's high-resolution time source when this event was created.
240 * @since Log4J 2.4
241 */
242 long getNanoTime();
243 }