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