001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache license, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the license for the specific language governing permissions and
015 * limitations under the license.
016 */
017
018package org.apache.logging.log4j.core;
019
020import java.io.Serializable;
021import java.util.Map;
022
023import org.apache.logging.log4j.Level;
024import org.apache.logging.log4j.Marker;
025import org.apache.logging.log4j.ThreadContext;
026import org.apache.logging.log4j.core.impl.Log4jLogEvent;
027import org.apache.logging.log4j.core.impl.ThrowableProxy;
028import org.apache.logging.log4j.message.Message;
029import org.apache.logging.log4j.message.ReusableMessage;
030import org.apache.logging.log4j.util.ReadOnlyStringMap;
031
032/**
033 * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
034 * may be transmitted over a network connection, output in a
035 * {@link org.apache.logging.log4j.core.layout.SerializedLayout}, and many other uses. Besides containing a
036 * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
037 * {@link org.apache.logging.log4j.Level} that the message was logged at. If a
038 * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
039 * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
040 * {@link #getContextMap()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
041 * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
042 * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
043 * and deserialized properly without causing problems if the exception class is not available on the other end.
044 * <p>
045 * Since version 2.7, {@link #getContextMap()} is deprecated in favor of {@link #getContextData()}, which
046 * can carry both {@code ThreadContext} data as well as other context data supplied by the
047 * {@linkplain org.apache.logging.log4j.core.impl.ContextDataInjectorFactory configured}
048 * {@link ContextDataInjector}.
049 * </p>
050 */
051public interface LogEvent extends Serializable {
052
053    /**
054     * Returns an immutable version of this log event, which MAY BE a copy of this event.
055     *  
056     * @return an immutable version of this log event
057     */
058    LogEvent toImmutable();
059
060    /**
061     * Gets the context map (also know as Mapped Diagnostic Context or MDC).
062     *
063     * @return The context map, never {@code null}.
064     * @deprecated use {@link #getContextData()} instead
065     */
066    @Deprecated
067    Map<String, String> getContextMap();
068
069    /**
070     * Returns the {@code ReadOnlyStringMap} object holding context data key-value pairs.
071     * <p>
072     * Context data (also known as Mapped Diagnostic Context or MDC) is data that is set by the application to be
073     * included in all subsequent log events. The default source for context data is the {@link ThreadContext} (and
074     * <a href="https://logging.apache.org/log4j/2.x/manual/configuration.html#PropertySubstitution">properties</a>
075     * configured on the Logger that logged the event), but users can configure a custom {@link ContextDataInjector}
076     * to inject key-value pairs from any arbitrary source.
077     *
078     * @return the {@code ReadOnlyStringMap} object holding context data key-value pairs
079     * @see ContextDataInjector
080     * @see ThreadContext
081     * @since 2.7
082     */
083    ReadOnlyStringMap getContextData();
084
085    /**
086     * Gets the context stack (also known as Nested Diagnostic Context or NDC).
087     *
088     * @return The context stack, never {@code null}.
089     */
090    ThreadContext.ContextStack getContextStack();
091
092    /**
093     * Returns the fully qualified class name of the caller of the logging API.
094     *
095     * @return The fully qualified class name of the caller.
096     */
097    String getLoggerFqcn();
098
099    /**
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}