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}