Log File Settings

Please note that the feature describe here is only available in Platform 2.4.4+, 2.5.1+ and, once it's released 2.6.0+

OpenMRS uses the Apache Log4J2 project to support logging, which comes with a very rich set of configuration options for determining how messages are logged, determining which messages go where, etc. Previously, however, this configuration has been somewhat hidden or inaccessible to administrators. With the release of the above mentioned version, the Log4J2 settings can now be fully controlled via a log4j2.xml file placed either in the OpenMRS Application Data Directory or in the configuration sub-directory of the OpenMRS Application Data Directory.

The default OpenMRS logging configuration can be found on GitHub as part of the openmrs-core project. And looks something like this (as of Jan 12, 2022 ):

log4j2.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!--

    This Source Code Form is subject to the terms of the Mozilla Public License,
    v. 2.0. If a copy of the MPL was not distributed with this file, You can
    obtain one at http://mozilla.org/MPL/2.0/. OpenMRS is also distributed under
    the terms of the Healthcare Disclaimer located at http://openmrs.org/license.

    Copyright (C) OpenMRS Inc. OpenMRS is a registered trademark and the OpenMRS
    graphic logo is a trademark of OpenMRS Inc.

-->

<Configuration xmlns="http://logging.apache.org/log4j/2.0/config">
	<Properties>
		<!-- The default pattern is stored as a property so that it's only defined once.
		     It's also quite challenging to escape using Log4j2's variable substitution. -->
		<Property name="defaultPattern">%p - %C{1}.%M(%L) |%d{ISO8601}| %m%n</Property>
	</Properties>
	<Appenders>
		<!-- the console appender is not required but usually a good idea -->
		<Console name="CONSOLE" target="SYSTEM_OUT">
			<PatternLayout pattern="${openmrs:logLayout:-${defaultPattern}}" />
		</Console>
		<!-- OpenMRS should have an appender called "OPENMRS FILE APPENDER" that appends to a file -->
		<RollingFile name="OPENMRS FILE APPENDER"
					 fileName="${openmrs:logLocation:-${openmrs:applicationDirectory}}/openmrs.log"
					 filePattern="${openmrs:logLocation:-${openmrs:applicationDirectory}}/openmrs.%i.log">
			<PatternLayout pattern="${openmrs:logLayout:-${defaultPattern}}" />
			<Policies>
				<OnStartupTriggeringPolicy />
				<SizeBasedTriggeringPolicy size="10 MB" />
			</Policies>
			<DefaultRolloverStrategy max="1" />
		</RollingFile>
		<!-- The MEMORY_APPENDER is used to keep a subset of logging messages in memory to be displayed to the user.
		 	 If one is not configured here, it will be created automatically. -->
		<Memory name="MEMORY_APPENDER"
				bufferSize="200"> <!-- bufferSize is how many messages are kept in memory -->
			<PatternLayout pattern="${openmrs:logLayout:-${defaultPattern}}" />
		</Memory>
	</Appenders>
	<Loggers>
		<Logger name="org.apache" level="WARN" />
		<Logger name="org.hibernate" level="ERROR" />
		<Logger name="net.sf.ehcache" level="ERROR" />
		<Logger name="org.springframework" level="WARN" />
		<Logger name="org.openmrs" level="WARN" />
		<Logger name="liquibase" level="INFO" />
		<!-- 
			This controls the LoggingAdvice class that wraps around the OpenMRS services 
			WARN == don't log anything special for the services
			INFO == log all setters
			DEBUG == log all setters & log all getters & log execution time
		-->
		<Logger name="org.openmrs.api" level="INFO" />
		<Logger name="org.apache.fop" level="ERROR" />
		<!-- Hide the useless MissingResourceException -->
		<Logger name="org.springframework.context.support.ResourceBundleMessageSource" level="ERROR" />
		<Logger name="org.springframework.beans.factory.support.DefaultListableBeanFactory" level="ERROR" />
		<Root level="WARN">
			<AppenderRef ref="CONSOLE" />
			<AppenderRef ref="MEMORY_APPENDER" />
			<AppenderRef ref="OPENMRS FILE APPENDER" />
		</Root>
	</Loggers>
</Configuration>

Extensive details on how to configure Log4J2 can be found in the Log4J2 manual. However, there are some OpenMRS-specific points that are worth considering:

If you have an appender that writes to a file it should have the name OPENMRS FILE APPENDER as shown above. This will enable OpenMRS to tell you where your log file actually is.
The MEMORY_APPENDER is used to hold logging messages in memory for display, e.g. in the View System Logs link. You are not required to have this in your configuration, but if you do not, a memory appender with the default settings (100 entries using the pattern %p - %C{1}.%M(%L) |%d{ISO8601}| %m%n) will be automatically created and attached to the root logger for you.

In addition, as can be seen in the above file, OpenMRS exposes some OpenMRS-specific logging configuration settings, specifically:

openmrs:logLayout: this will be the value of the log.layout setting. If you want that setting to be able to control the log layout, you should use it in your appenders as shown above.
openmrs:logLocation: this will be the value of the log.location setting. If you want that setting to be able to control where the log file is output, you should use it as shown above.
openmrs:applicationDirectory: this will be the location of the OpenMRS Application Data Directory. It is useful for ensuring your logs are written there, if that is the desired behaviour.

NB If you do not use openmrs:logLayout and openmrs:logLocation in your log4j2 configuration file, then the log.layout and log.location settings will have no effect.