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 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}