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