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.message.Message;
028
029/**
030 * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
031 * may be transmitted over a network connection, output in a
032 * {@link org.apache.logging.log4j.core.layout.SerializedLayout}, and many other uses. Besides containing a
033 * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
034 * {@link org.apache.logging.log4j.Level} that the message was logged at. If a
035 * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
036 * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
037 * {@link #getContextMap()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
038 * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
039 * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
040 * and deserialized properly without causing problems if the exception class is not available on the other end.
041 */
042public interface LogEvent extends Serializable {
043
044    /**
045     * Gets the context map (also know as Mapped Diagnostic Context or MDC).
046     *
047     * @return The context map, never {@code null}.
048     */
049    Map<String, String> getContextMap();
050
051    /**
052     * Gets the context stack (also known as Nested Diagnostic Context or NDC).
053     *
054     * @return The context stack, never {@code null}.
055     */
056    ThreadContext.ContextStack getContextStack();
057
058    /**
059     * Returns the fully qualified class name of the caller of the logging API.
060     *
061     * @return The fully qualified class name of the caller.
062     */
063    String getLoggerFqcn();
064
065    /**
066     * Gets the level.
067     *
068     * @return level.
069     */
070    Level getLevel();
071
072    /**
073     * Gets the logger name.
074     *
075     * @return logger name, may be {@code null}.
076     */
077    String getLoggerName();
078
079    /**
080     * Gets the Marker associated with the event.
081     *
082     * @return Marker or {@code null} if no Marker was defined on this LogEvent
083     */
084    Marker getMarker();
085
086    /**
087     * Gets the message associated with the event.
088     *
089     * @return message.
090     */
091    Message getMessage();
092
093    /**
094     * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
095     *
096     * @return milliseconds since midnight, January 1, 1970 UTC.
097     * @see java.lang.System#currentTimeMillis()
098     */
099    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 the 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 the thread ID.
118     *
119     * @return thread ID.
120     * @since 2.6
121     */
122    long getThreadId();
123
124    /**
125     * Gets the thread priority.
126     *
127     * @return thread priority.
128     * @since 2.6
129     */
130    int getThreadPriority();
131
132    /**
133     * Gets throwable associated with logging request.
134     *
135     * <p>Convenience method for {@code ThrowableProxy.getThrowable();}</p>
136     *
137     * @return throwable, may be null.
138     */
139    Throwable getThrown();
140
141    /**
142     * Gets throwable proxy associated with logging request.
143     *
144     * @return throwable, may be null.
145     */
146    ThrowableProxy getThrownProxy();
147
148    /**
149     * Returns {@code true} if this event is the last one in a batch, {@code false} otherwise. Used by asynchronous
150     * Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient
151     * alternative to the {@code immediateFlush=true} configuration.
152     *
153     * @return whether this event is the last one in a batch.
154     */
155    // see also LOG4J2-164
156    boolean isEndOfBatch();
157
158    /**
159     * Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
160     * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
161     * another thread.
162     *
163     * @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
164     * @see #getSource()
165     */
166    // see also LOG4J2-153
167    boolean isIncludeLocation();
168
169    /**
170     * Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to
171     * buffered downstream components when to flush to disk, as a more efficient alternative to the
172     * {@code immediateFlush=true} configuration.
173     *
174     * @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
175     */
176    void setEndOfBatch(boolean endOfBatch);
177
178    /**
179     * Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
180     * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
181     * another thread.
182     *
183     * @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false}
184     *                         otherwise.
185     * @see #getSource()
186     */
187    void setIncludeLocation(boolean locationRequired);
188
189    /**
190     * Returns the value of the running Java Virtual Machine's high-resolution time source when this event was created,
191     * or a dummy value if it is known that this value will not be used downstream.
192     * @return The value of the running Java Virtual Machine's high-resolution time source when this event was created.
193     * @since Log4J 2.4
194     */
195    long getNanoTime();
196}