h3. Configure logging In order to detect and analyze problems, adjusting the log level of a server can be a valuable tool. This section describes how to configure logging within a standalone ApacheDS. h4. ApacheDS and logging ApacheDS uses [SLF4J|http://www.slf4j.org/|www.slf4j.org] as its logging solution. This is a simple facade for various logging APIs. The default for ApacheDS 2.0 is [log4j|http://logging.apache.org/log4j/|logging.apache.org]. h4. Default behavior after installation Without modification, the ApacheDS default instance writes log files in the directory _/instances/default/log/_. Besides stdout, a [RollingFileAppender|http://logging.apache.org/log4j/docs/api/org/apache/log4j/RollingFileAppender.html|log4j javadoc] is used to collect warnings and errors. It backups the log files when they reach a certain size. Here is what the default configuration file _log4j.properties_ for the default instance, which is located in _/instances/default/conf/_, looks like. The name of the _RollingFileAppender_ is "R": {code} log4j.rootCategory=WARN, R, stdout log4j.appender.stdout=org.apache.log4j.ConsoleAppender log4j.appender.stdout.layout=org.apache.log4j.PatternLayout log4j.appender.R=org.apache.log4j.RollingFileAppender log4j.appender.R.File=${apacheds.log.dir}/apacheds-rolling.log log4j.appender.R.MaxFileSize=1024KB # Keep some backup files log4j.appender.R.MaxBackupIndex=5 log4j.appender.R.layout=org.apache.log4j.PatternLayout log4j.appender.R.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n log4j.appender.stdout.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n # with these we'll not get innundated when switching to DEBUG log4j.logger.org.apache.directory.shared.ldap.name=WARN log4j.logger.org.springframework=WARN log4j.logger.org.apache.directory.shared.codec=WARN log4j.logger.org.apache.directory.shared.asn1=WARN {code} In this file, "R" is configured like this: || Property name || Value in file above || Meaning || | File | $\{apacheds.log.dir\}/apacheds-rolling.log | path to the output log file | | MaxFileSize | 1024KB | maximum size that the output file is allowed to reach before being rolled over to backup files | | MaxBackupIndex | 5 | number of backup files kept | | layout.ConversionPattern | \[%d\{HH:mm:ss\}\] %p \[%c\] - %m%n | format string for logging events | If the default logging does not meet your requirements, you can easily adjust the configuration to your needs. h4. Adjusting logging to your needs h5. Log file location (where the log files are placed) The location where the log files are placed can be changed. h6. Windows As you have noticed, the configuration for the log file within _log4j.properties_ uses a variable called $\{apacheds.log.dir\}. The variable is handed over to ApacheDS via the wrapper. This is configured in _/conf/apacheds.conf_: {noformat} ... # Java Additional Parameters wrapper.java.additional.1=-Dlog4j.configuration="file:///%INSTANCE_HOME%/%INSTANCE%/conf/log4j.properties" wrapper.java.additional.2=-Dapacheds.var.dir="%INSTANCE_HOME%/%INSTANCE%" wrapper.java.additional.3=-Dapacheds.log.dir="%INSTANCE_HOME%/%INSTANCE%/log" wrapper.java.additional.4=-Dapacheds.run.dir="%INSTANCE_HOME%/%INSTANCE%/run" wrapper.java.additional.5=-Dapacheds.instance=%INSTANCE% ... {noformat} It is possible, to adjust the value here for all ApacheDS instances. For the _default_ instance (or any other instance), you may change the value within the file _/instances/default/conf/apacheds.conf_ as well; it overrides the values of the general file. h6. Linux/MacOS/Solaris to be investigated, whether it is different than on Windows h5. Log level (how detailed the logs are) The following log levels from log4j are used for messages within ApacheDS: || Level || Description from log4j documentation || | DEBUG | designates fine-grained informational events that are most useful to debug an application | | INFO| designates informational messages that highlight the progress of the application at coarse-grained level | | WARN| designates potentially harmful situations | | ERROR| designates error events that might still allow the application to continue running | | FATAL | designates very severe error events that will presumably lead the application to abort | The default (global) log level in the configuration is _WARN_. All messages of level WARN and more severe (ERROR, FATAL) are written to the rolling log file. The easiest way to get finer log messages is to change it like this {code} log4j.rootCategory=DEBUG, stdout, R ... {code} These detailed log messages took much file space and time and therefore should only be enabled globally in order to analyze problems. It is possible to configure the logging more fine grained by using categories. Within the default configuration there are some examples: {code} ... # with these we'll not get innundated when switching to DEBUG log4j.logger.org.apache.directory.shared.ldap.name=WARN log4j.logger.org.springframework=WARN log4j.logger.org.apache.directory.shared.codec=WARN log4j.logger.org.apache.directory.shared.asn1=WARN {code} If the global level is switched to DEBUG, these definitions override the setting with WARN for certain areas and therefore keep the file a little bit smaller. Learn more about the concept of categories in the [Short introduction to log4j|http://logging.apache.org/log4j/docs/manual.html]. h5. Format for log messages The format of each line within a log file is controlled by a pattern. For the _RollingFileAppender_ in the default configuration it looks like this {code} ... log4j.appender.R.layout=org.apache.log4j.PatternLayout log4j.appender.R.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n ... {code} Some examples lines within the log file, formatted with the pattern "\[%d\{HH:mm:ss\}\] %p \[%c\] - %m%n" are: {code} ... [12:29:03] WARN [org.apache.directory.server.core.DefaultDirectoryService] - You didn't change the admin password of directory service instance 'default'. Please update the admin password as soon as possible to prevent a possible security breach. ... [12:29:05] INFO [org.apache.directory.server.jndi.ServerContextFactory] - Successful bind of an LDAP Service (636) is complete. [12:29:05] INFO [org.apache.directory.server.Service] - server: started in 6750 milliseconds ... {code} The pattern uses the following conversion characters: || Character || Outputs || | %d | date of the logging event in the given format. like "12:29:05" for %d\{HH:mm:ss\} | | %p | priority (level) of the logging event, like "INFO" or "WARN" | | %c | category of the logging event, like "org.apache.directory.server.Service" | | %m | application supplied message associated with the logging event | | %n | platform dependent line separator | The [javadoc of log4j|http://logging.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html|javadoc of log4j PatternLayout class] contains a table with all valid %-characters and their meaning. Simple adjust the pattern in the _log4j.properties file_ to get the log format of your choice, for instance {code} log4j.appender.R.layout.ConversionPattern=[%d{dd.MM.yyyy HH:mm:ss}] %p: %c{1}.%M() - %m%n {code} leads to messages of this form: {code} ... [29.12.2006 13:50:44] INFO: ServerContextFactory.startLDAP0() - Successful bind of an LDAP Service (636) is complete. [29.12.2006 13:50:44] INFO: Service.init() - server: started in 3016 milliseconds ... {code} {warning:title=Warning} "Generating caller location information like with %M or %L is extremely slow. Its use should be avoided unless execution speed is not an issue." (from the log4j documentation) {warning} h5. Advanced log4j configuration You can take advantage of other features of log4j as well, such as other appenders like the daily rolling file appender. And you can configure logging to make it easier for you to view the messages with tools like Log Factor 5 or [Chainsaw|http://logging.apache.org/log4j/docs/chainsaw.html|logging.apache.org]. Learn more about log4j and related tools at its [homepage|http://logging.apache.org/log4j/docs/index.html|log4j homepage]. h4. Resources * [Short introduction to log4j|http://logging.apache.org/log4j/docs/manual.html|logging.apache.org]