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.core.time.Instant; 28 import org.apache.logging.log4j.message.Message; 29 import org.apache.logging.log4j.util.ReadOnlyStringMap; 30 31 /** 32 * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it 33 * may be transmitted over a network connection, output in a 34 * {@link org.apache.logging.log4j.core.layout.SerializedLayout}, and many other uses. Besides containing a 35 * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding 36 * {@link org.apache.logging.log4j.Level} that the message was logged at. If a 37 * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the 38 * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via 39 * {@link #getContextMap()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log 40 * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will 41 * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized 42 * and deserialized properly without causing problems if the exception class is not available on the other end. 43 * <p> 44 * Since version 2.7, {@link #getContextMap()} is deprecated in favor of {@link #getContextData()}, which 45 * can carry both {@code ThreadContext} data as well as other context data supplied by the 46 * {@linkplain org.apache.logging.log4j.core.impl.ContextDataInjectorFactory configured} 47 * {@link ContextDataInjector}. 48 * </p> 49 */ 50 public interface LogEvent extends Serializable { 51 52 /** 53 * Returns an immutable version of this log event, which MAY BE a copy of this event. 54 * 55 * @return an immutable version of this log event 56 */ 57 LogEvent toImmutable(); 58 59 /** 60 * Gets the context map (also know as Mapped Diagnostic Context or MDC). 61 * 62 * @return The context map, never {@code null}. 63 * @deprecated use {@link #getContextData()} instead 64 */ 65 @Deprecated 66 Map<String, String> getContextMap(); 67 68 /** 69 * Returns the {@code ReadOnlyStringMap} object holding context data key-value pairs. 70 * <p> 71 * Context data (also known as Mapped Diagnostic Context or MDC) is data that is set by the application to be 72 * included in all subsequent log events. The default source for context data is the {@link ThreadContext} (and 73 * <a href="https://logging.apache.org/log4j/2.x/manual/configuration.html#PropertySubstitution">properties</a> 74 * configured on the Logger that logged the event), but users can configure a custom {@link ContextDataInjector} 75 * to inject key-value pairs from any arbitrary source. 76 * 77 * @return the {@code ReadOnlyStringMap} object holding context data key-value pairs 78 * @see ContextDataInjector 79 * @see ThreadContext 80 * @since 2.7 81 */ 82 ReadOnlyStringMap getContextData(); 83 84 /** 85 * Gets the context stack (also known as Nested Diagnostic Context or NDC). 86 * 87 * @return The context stack, never {@code null}. 88 */ 89 ThreadContext.ContextStack getContextStack(); 90 91 /** 92 * Returns the fully qualified class name of the caller of the logging API. 93 * 94 * @return The fully qualified class name of the caller. 95 */ 96 String getLoggerFqcn(); 97 98 /** 99 * 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 Instant 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 Instant 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 }