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
29 /**
30 * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
31 * may be transmitted over a network connection, output in a
32 * {@link org.apache.logging.log4j.core.layout.SerializedLayout}, and many other uses. Besides containing a
33 * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
34 * {@link org.apache.logging.log4j.Level} that the message was logged at. If a
35 * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
36 * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
37 * {@link #getContextMap()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
38 * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
39 * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
40 * and deserialized properly without causing problems if the exception class is not available on the other end.
41 */
42 public interface LogEvent extends Serializable {
43
44 /**
45 * Gets the context map (also know as Mapped Diagnostic Context or MDC).
46 *
47 * @return The context map, never {@code null}.
48 */
49 Map<String, String> getContextMap();
50
51 /**
52 * Gets the context stack (also known as Nested Diagnostic Context or NDC).
53 *
54 * @return The context stack, never {@code null}.
55 */
56 ThreadContext.ContextStack getContextStack();
57
58 /**
59 * Returns the fully qualified class name of the caller of the logging API.
60 *
61 * @return The fully qualified class name of the caller.
62 */
63 String getLoggerFqcn();
64
65 /**
66 * Gets the level.
67 *
68 * @return level.
69 */
70 Level getLevel();
71
72 /**
73 * Gets the logger name.
74 *
75 * @return logger name, may be {@code null}.
76 */
77 String getLoggerName();
78
79 /**
80 * Gets the Marker associated with the event.
81 *
82 * @return Marker or {@code null} if no Marker was defined on this LogEvent
83 */
84 Marker getMarker();
85
86 /**
87 * Gets the message associated with the event.
88 *
89 * @return message.
90 */
91 Message getMessage();
92
93 /**
94 * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
95 *
96 * @return milliseconds since midnight, January 1, 1970 UTC.
97 * @see java.lang.System#currentTimeMillis()
98 */
99 long getTimeMillis();
100
101 /**
102 * Gets the source of logging request.
103 *
104 * @return source of logging request, may be null.
105 */
106 StackTraceElement getSource();
107
108 /**
109 * Gets thread name.
110 *
111 * @return thread name, may be null.
112 * TODO guess this could go into a thread context object too. (RG) Why?
113 */
114 String getThreadName();
115
116 /**
117 * Gets throwable associated with logging request.
118 *
119 * <p>Convenience method for {@code ThrowableProxy.getThrowable();}</p>
120 *
121 * @return throwable, may be null.
122 */
123 Throwable getThrown();
124
125 /**
126 * Gets throwable proxy associated with logging request.
127 *
128 * @return throwable, may be null.
129 */
130 ThrowableProxy getThrownProxy();
131
132 /**
133 * Returns {@code true} if this event is the last one in a batch, {@code false} otherwise. Used by asynchronous
134 * Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient
135 * alternative to the {@code immediateFlush=true} configuration.
136 *
137 * @return whether this event is the last one in a batch.
138 */
139 // see also LOG4J2-164
140 boolean isEndOfBatch();
141
142 /**
143 * Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
144 * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
145 * another thread.
146 *
147 * @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
148 * @see #getSource()
149 */
150 // see also LOG4J2-153
151 boolean isIncludeLocation();
152
153 /**
154 * Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to
155 * buffered downstream components when to flush to disk, as a more efficient alternative to the
156 * {@code immediateFlush=true} configuration.
157 *
158 * @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
159 */
160 void setEndOfBatch(boolean endOfBatch);
161
162 /**
163 * Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
164 * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
165 * another thread.
166 *
167 * @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false}
168 * otherwise.
169 * @see #getSource()
170 */
171 void setIncludeLocation(boolean locationRequired);
172
173 }