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