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.ThrowableProxy;
027import org.apache.logging.log4j.core.time.Instant;
028import org.apache.logging.log4j.message.Message;
029import org.apache.logging.log4j.util.ReadOnlyStringMap;
030
031/**
032 * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
033 * may be transmitted over a network connection, output in a
034 * {@link org.apache.logging.log4j.core.layout.SerializedLayout}, and many other uses. Besides containing a
035 * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
036 * {@link org.apache.logging.log4j.Level} that the message was logged at. If a
037 * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
038 * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
039 * {@link #getContextMap()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
040 * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
041 * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
042 * and deserialized properly without causing problems if the exception class is not available on the other end.
043 * <p>
044 * Since version 2.7, {@link #getContextMap()} is deprecated in favor of {@link #getContextData()}, which
045 * can carry both {@code ThreadContext} data as well as other context data supplied by the
046 * {@linkplain org.apache.logging.log4j.core.impl.ContextDataInjectorFactory configured}
047 * {@link ContextDataInjector}.
048 * </p>
049 */
050public interface LogEvent extends Serializable {
051
052    /**
053     * Returns an immutable version of this log event, which MAY BE a copy of this event.
054     *  
055     * @return an immutable version of this log event
056     */
057    LogEvent toImmutable();
058
059    /**
060     * Gets the context map (also know as Mapped Diagnostic Context or MDC).
061     *
062     * @return The context map, never {@code null}.
063     * @deprecated use {@link #getContextData()} instead
064     */
065    @Deprecated
066    Map<String, String> getContextMap();
067
068    /**
069     * Returns the {@code ReadOnlyStringMap} object holding context data key-value pairs.
070     * <p>
071     * Context data (also known as Mapped Diagnostic Context or MDC) is data that is set by the application to be
072     * included in all subsequent log events. The default source for context data is the {@link ThreadContext} (and
073     * <a href="https://logging.apache.org/log4j/2.x/manual/configuration.html#PropertySubstitution">properties</a>
074     * configured on the Logger that logged the event), but users can configure a custom {@link ContextDataInjector}
075     * to inject key-value pairs from any arbitrary source.
076     *
077     * @return the {@code ReadOnlyStringMap} object holding context data key-value pairs
078     * @see ContextDataInjector
079     * @see ThreadContext
080     * @since 2.7
081     */
082    ReadOnlyStringMap getContextData();
083
084    /**
085     * Gets the context stack (also known as Nested Diagnostic Context or NDC).
086     *
087     * @return The context stack, never {@code null}.
088     */
089    ThreadContext.ContextStack getContextStack();
090
091    /**
092     * Returns the fully qualified class name of the caller of the logging API.
093     *
094     * @return The fully qualified class name of the caller.
095     */
096    String getLoggerFqcn();
097
098    /**
099     * Gets the level.
100     *
101     * @return level.
102     */
103    Level getLevel();
104
105    /**
106     * Gets the logger name.
107     *
108     * @return logger name, may be {@code null}.
109     */
110    String getLoggerName();
111
112    /**
113     * Gets the Marker associated with the event.
114     *
115     * @return Marker or {@code null} if no Marker was defined on this LogEvent
116     */
117    Marker getMarker();
118
119    /**
120     * Gets the message associated with the event.
121     *
122     * @return message.
123     */
124    Message getMessage();
125
126    /**
127     * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
128     * Use {@link #getInstant()} to get higher precision timestamp information if available on this platform.
129     *
130     * @return the milliseconds component of this log event's {@linkplain #getInstant() timestamp}
131     * @see java.lang.System#currentTimeMillis()
132     */
133    long getTimeMillis();
134
135    /**
136     * Returns the timestamp when the message was logged.
137     * <p>
138     * <b>Caution</b>: if this {@code LogEvent} implementation is mutable and reused for multiple consecutive log messages,
139     * then the {@code Instant} object returned by this method is also mutable and reused.
140     * Client code should not keep a reference to the returned object but make a copy instead.
141     * </p>
142     *
143     * @return the {@code Instant} holding timestamp details for this log event
144     * @since 2.11
145     */
146    Instant getInstant();
147
148    /**
149     * Gets the source of logging request.
150     *
151     * @return source of logging request, may be null.
152     */
153    StackTraceElement getSource();
154
155    /**
156     * Gets the thread name.
157     *
158     * @return thread name, may be null.
159     * TODO guess this could go into a thread context object too. (RG) Why?
160     */
161    String getThreadName();
162
163    /**
164     * Gets the thread ID.
165     *
166     * @return thread ID.
167     * @since 2.6
168     */
169    long getThreadId();
170
171    /**
172     * Gets the thread priority.
173     *
174     * @return thread priority.
175     * @since 2.6
176     */
177    int getThreadPriority();
178
179    /**
180     * Gets throwable associated with logging request.
181     *
182     * <p>Convenience method for {@code ThrowableProxy.getThrowable();}</p>
183     *
184     * @return throwable, may be null.
185     */
186    Throwable getThrown();
187
188    /**
189     * Gets throwable proxy associated with logging request.
190     *
191     * @return throwable, may be null.
192     */
193    ThrowableProxy getThrownProxy();
194
195    /**
196     * Returns {@code true} if this event is the last one in a batch, {@code false} otherwise. Used by asynchronous
197     * Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient
198     * alternative to the {@code immediateFlush=true} configuration.
199     *
200     * @return whether this event is the last one in a batch.
201     */
202    // see also LOG4J2-164
203    boolean isEndOfBatch();
204
205    /**
206     * Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
207     * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
208     * another thread.
209     *
210     * @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
211     * @see #getSource()
212     */
213    // see also LOG4J2-153
214    boolean isIncludeLocation();
215
216    /**
217     * Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to
218     * buffered downstream components when to flush to disk, as a more efficient alternative to the
219     * {@code immediateFlush=true} configuration.
220     *
221     * @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
222     */
223    void setEndOfBatch(boolean endOfBatch);
224
225    /**
226     * Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
227     * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
228     * another thread.
229     *
230     * @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false}
231     *                         otherwise.
232     * @see #getSource()
233     */
234    void setIncludeLocation(boolean locationRequired);
235
236    /**
237     * Returns the value of the running Java Virtual Machine's high-resolution time source when this event was created,
238     * or a dummy value if it is known that this value will not be used downstream.
239     * @return The value of the running Java Virtual Machine's high-resolution time source when this event was created.
240     * @since Log4J 2.4
241     */
242    long getNanoTime();
243}