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 */ 017package org.apache.logging.log4j.core.async; 018 019import java.util.Arrays; 020import java.util.List; 021import java.util.concurrent.TimeUnit; 022 023import org.apache.logging.log4j.Level; 024import org.apache.logging.log4j.LogManager; 025import org.apache.logging.log4j.core.Core; 026import org.apache.logging.log4j.core.Filter; 027import org.apache.logging.log4j.core.LogEvent; 028import org.apache.logging.log4j.core.config.AppenderRef; 029import org.apache.logging.log4j.core.config.Configuration; 030import org.apache.logging.log4j.core.config.LoggerConfig; 031import org.apache.logging.log4j.core.config.Node; 032import org.apache.logging.log4j.core.config.Property; 033import org.apache.logging.log4j.core.config.plugins.Plugin; 034import org.apache.logging.log4j.core.config.plugins.PluginAttribute; 035import org.apache.logging.log4j.core.config.plugins.PluginConfiguration; 036import org.apache.logging.log4j.core.config.plugins.PluginElement; 037import org.apache.logging.log4j.core.config.plugins.PluginFactory; 038import org.apache.logging.log4j.core.config.plugins.validation.constraints.Required; 039import org.apache.logging.log4j.core.jmx.RingBufferAdmin; 040import org.apache.logging.log4j.core.util.Booleans; 041import org.apache.logging.log4j.spi.AbstractLogger; 042import org.apache.logging.log4j.util.Strings; 043 044/** 045 * Asynchronous Logger object that is created via configuration and can be 046 * combined with synchronous loggers. 047 * <p> 048 * AsyncLoggerConfig is a logger designed for high throughput and low latency 049 * logging. It does not perform any I/O in the calling (application) thread, but 050 * instead hands off the work to another thread as soon as possible. The actual 051 * logging is performed in the background thread. It uses 052 * <a href="https://lmax-exchange.github.io/disruptor/">LMAX Disruptor</a> for 053 * inter-thread communication. 054 * <p> 055 * To use AsyncLoggerConfig, specify {@code <asyncLogger>} or 056 * {@code <asyncRoot>} in configuration. 057 * <p> 058 * Note that for performance reasons, this logger does not include source 059 * location by default. You need to specify {@code includeLocation="true"} in 060 * the configuration or any %class, %location or %line conversion patterns in 061 * your log4j.xml configuration will produce either a "?" character or no output 062 * at all. 063 * <p> 064 * For best performance, use AsyncLoggerConfig with the RandomAccessFileAppender or 065 * RollingRandomAccessFileAppender, with immediateFlush=false. These appenders have 066 * built-in support for the batching mechanism used by the Disruptor library, 067 * and they will flush to disk at the end of each batch. This means that even 068 * with immediateFlush=false, there will never be any items left in the buffer; 069 * all log events will all be written to disk in a very efficient manner. 070 */ 071@Plugin(name = "asyncLogger", category = Node.CATEGORY, printObject = true) 072public class AsyncLoggerConfig extends LoggerConfig { 073 074 private static final ThreadLocal<Boolean> ASYNC_LOGGER_ENTERED = new ThreadLocal<Boolean>() { 075 @Override 076 protected Boolean initialValue() { 077 return Boolean.FALSE; 078 } 079 }; 080 081 private final AsyncLoggerConfigDelegate delegate; 082 083 protected AsyncLoggerConfig(final String name, 084 final List<AppenderRef> appenders, final Filter filter, 085 final Level level, final boolean additive, 086 final Property[] properties, final Configuration config, 087 final boolean includeLocation) { 088 super(name, appenders, filter, level, additive, properties, config, 089 includeLocation); 090 delegate = config.getAsyncLoggerConfigDelegate(); 091 delegate.setLogEventFactory(getLogEventFactory()); 092 } 093 094 @Override 095 protected void log(final LogEvent event, final LoggerConfigPredicate predicate) { 096 // See LOG4J2-2301 097 if (predicate == LoggerConfigPredicate.ALL && 098 ASYNC_LOGGER_ENTERED.get() == Boolean.FALSE && 099 // Optimization: AsyncLoggerConfig is identical to LoggerConfig 100 // when no appenders are present. Avoid splitting for synchronous 101 // and asynchronous execution paths until encountering an 102 // AsyncLoggerConfig with appenders. 103 hasAppenders()) { 104 // This is the first AsnycLoggerConfig encountered by this LogEvent 105 ASYNC_LOGGER_ENTERED.set(Boolean.TRUE); 106 try { 107 // Detect the first time we encounter an AsyncLoggerConfig. We must log 108 // to all non-async loggers first. 109 super.log(event, LoggerConfigPredicate.SYNCHRONOUS_ONLY); 110 // Then pass the event to the background thread where 111 // all async logging is executed. It is important this 112 // happens at most once and after all synchronous loggers 113 // have been invoked, because we lose parameter references 114 // from reusable messages. 115 logToAsyncDelegate(event); 116 } finally { 117 ASYNC_LOGGER_ENTERED.set(Boolean.FALSE); 118 } 119 } else { 120 super.log(event, predicate); 121 } 122 } 123 124 @Override 125 protected void callAppenders(final LogEvent event) { 126 super.callAppenders(event); 127 } 128 129 private void logToAsyncDelegate(final LogEvent event) { 130 if (!isFiltered(event)) { 131 // Passes on the event to a separate thread that will call 132 // asyncCallAppenders(LogEvent). 133 populateLazilyInitializedFields(event); 134 if (!delegate.tryEnqueue(event, this)) { 135 handleQueueFull(event); 136 } 137 } 138 } 139 140 private void handleQueueFull(final LogEvent event) { 141 if (AbstractLogger.getRecursionDepth() > 1) { // LOG4J2-1518, LOG4J2-2031 142 // If queue is full AND we are in a recursive call, call appender directly to prevent deadlock 143 AsyncQueueFullMessageUtil.logWarningToStatusLogger(); 144 logToAsyncLoggerConfigsOnCurrentThread(event); 145 } else { 146 // otherwise, we leave it to the user preference 147 final EventRoute eventRoute = delegate.getEventRoute(event.getLevel()); 148 eventRoute.logMessage(this, event); 149 } 150 } 151 152 private void populateLazilyInitializedFields(final LogEvent event) { 153 event.getSource(); 154 event.getThreadName(); 155 } 156 157 void logInBackgroundThread(final LogEvent event) { 158 delegate.enqueueEvent(event, this); 159 } 160 161 /** 162 * Called by AsyncLoggerConfigHelper.RingBufferLog4jEventHandler. 163 * 164 * This method will log the provided event to only configs of type {@link AsyncLoggerConfig} (not 165 * default {@link LoggerConfig} definitions), which will be invoked on the <b>calling thread</b>. 166 */ 167 void logToAsyncLoggerConfigsOnCurrentThread(final LogEvent event) { 168 log(event, LoggerConfigPredicate.ASYNCHRONOUS_ONLY); 169 } 170 171 private String displayName() { 172 return LogManager.ROOT_LOGGER_NAME.equals(getName()) ? LoggerConfig.ROOT : getName(); 173 } 174 175 @Override 176 public void start() { 177 LOGGER.trace("AsyncLoggerConfig[{}] starting...", displayName()); 178 super.start(); 179 } 180 181 @Override 182 public boolean stop(final long timeout, final TimeUnit timeUnit) { 183 setStopping(); 184 super.stop(timeout, timeUnit, false); 185 LOGGER.trace("AsyncLoggerConfig[{}] stopping...", displayName()); 186 setStopped(); 187 return true; 188 } 189 190 /** 191 * Creates and returns a new {@code RingBufferAdmin} that instruments the 192 * ringbuffer of this {@code AsyncLoggerConfig}. 193 * 194 * @param contextName name of the {@code LoggerContext} 195 * @return a new {@code RingBufferAdmin} that instruments the ringbuffer 196 */ 197 public RingBufferAdmin createRingBufferAdmin(final String contextName) { 198 return delegate.createRingBufferAdmin(contextName, getName()); 199 } 200 201 /** 202 * Factory method to create a LoggerConfig. 203 * 204 * @param additivity True if additive, false otherwise. 205 * @param levelName The Level to be associated with the Logger. 206 * @param loggerName The name of the Logger. 207 * @param includeLocation "true" if location should be passed downstream 208 * @param refs An array of Appender names. 209 * @param properties Properties to pass to the Logger. 210 * @param config The Configuration. 211 * @param filter A Filter. 212 * @return A new LoggerConfig. 213 * @deprecated use {@link #createLogger(boolean, Level, String, String, AppenderRef[], Property[], Configuration, Filter)} 214 */ 215 @Deprecated 216 public static LoggerConfig createLogger( 217 final String additivity, 218 final String levelName, 219 final String loggerName, 220 final String includeLocation, 221 final AppenderRef[] refs, 222 final Property[] properties, 223 final Configuration config, 224 final Filter filter) { 225 if (loggerName == null) { 226 LOGGER.error("Loggers cannot be configured without a name"); 227 return null; 228 } 229 230 final List<AppenderRef> appenderRefs = Arrays.asList(refs); 231 Level level; 232 try { 233 level = Level.toLevel(levelName, Level.ERROR); 234 } catch (final Exception ex) { 235 LOGGER.error( 236 "Invalid Log level specified: {}. Defaulting to Error", 237 levelName); 238 level = Level.ERROR; 239 } 240 final String name = loggerName.equals(LoggerConfig.ROOT) ? Strings.EMPTY : loggerName; 241 final boolean additive = Booleans.parseBoolean(additivity, true); 242 243 return new AsyncLoggerConfig(name, appenderRefs, filter, level, 244 additive, properties, config, includeLocation(includeLocation)); 245 } 246 247 /** 248 * Factory method to create a LoggerConfig. 249 * 250 * @param additivity True if additive, false otherwise. 251 * @param level The Level to be associated with the Logger. 252 * @param loggerName The name of the Logger. 253 * @param includeLocation "true" if location should be passed downstream 254 * @param refs An array of Appender names. 255 * @param properties Properties to pass to the Logger. 256 * @param config The Configuration. 257 * @param filter A Filter. 258 * @return A new LoggerConfig. 259 * @since 3.0 260 */ 261 @PluginFactory 262 public static LoggerConfig createLogger( 263 @PluginAttribute(value = "additivity", defaultBoolean = true) final boolean additivity, 264 @PluginAttribute("level") final Level level, 265 @Required(message = "Loggers cannot be configured without a name") @PluginAttribute("name") final String loggerName, 266 @PluginAttribute("includeLocation") final String includeLocation, 267 @PluginElement("AppenderRef") final AppenderRef[] refs, 268 @PluginElement("Properties") final Property[] properties, 269 @PluginConfiguration final Configuration config, 270 @PluginElement("Filter") final Filter filter) { 271 final String name = loggerName.equals(ROOT) ? Strings.EMPTY : loggerName; 272 return new AsyncLoggerConfig(name, Arrays.asList(refs), filter, level, additivity, properties, config, 273 includeLocation(includeLocation)); 274 } 275 276 // Note: for asynchronous loggers, includeLocation default is FALSE 277 protected static boolean includeLocation(final String includeLocationConfigValue) { 278 return Boolean.parseBoolean(includeLocationConfigValue); 279 } 280 281 /** 282 * An asynchronous root Logger. 283 */ 284 @Plugin(name = "asyncRoot", category = Core.CATEGORY_NAME, printObject = true) 285 public static class RootLogger extends LoggerConfig { 286 287 /** 288 * @deprecated use {@link #createLogger(String, Level, String, AppenderRef[], Property[], Configuration, Filter)} 289 */ 290 @Deprecated 291 public static LoggerConfig createLogger( 292 final String additivity, 293 final String levelName, 294 final String includeLocation, 295 final AppenderRef[] refs, 296 final Property[] properties, 297 final Configuration config, 298 final Filter filter) { 299 final List<AppenderRef> appenderRefs = Arrays.asList(refs); 300 Level level = null; 301 try { 302 level = Level.toLevel(levelName, Level.ERROR); 303 } catch (final Exception ex) { 304 LOGGER.error("Invalid Log level specified: {}. Defaulting to Error", levelName); 305 level = Level.ERROR; 306 } 307 final boolean additive = Booleans.parseBoolean(additivity, true); 308 return new AsyncLoggerConfig(LogManager.ROOT_LOGGER_NAME, 309 appenderRefs, filter, level, additive, properties, config, 310 AsyncLoggerConfig.includeLocation(includeLocation)); 311 } 312 313 /** 314 * @since 3.0 315 */ 316 @PluginFactory 317 public static LoggerConfig createLogger( 318 @PluginAttribute("additivity") final String additivity, 319 @PluginAttribute("level") final Level level, 320 @PluginAttribute("includeLocation") final String includeLocation, 321 @PluginElement("AppenderRef") final AppenderRef[] refs, 322 @PluginElement("Properties") final Property[] properties, 323 @PluginConfiguration final Configuration config, 324 @PluginElement("Filter") final Filter filter) { 325 final List<AppenderRef> appenderRefs = Arrays.asList(refs); 326 final Level actualLevel = level == null ? Level.ERROR : level; 327 final boolean additive = Booleans.parseBoolean(additivity, true); 328 return new AsyncLoggerConfig(LogManager.ROOT_LOGGER_NAME, appenderRefs, filter, actualLevel, additive, 329 properties, config, AsyncLoggerConfig.includeLocation(includeLocation)); 330 } 331 } 332}