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.
ApacheDS and logging
ApacheDS 1.5 uses SLF4J as its logging solution. This is a simple facade for various logging APIs. The default for ApacheDS 1.5 is log4j.
Default behavior after installation
By default, ApacheDS writes log files in the directory <APACHDS_HOME>/var/log/. Besides stdout, a RollingFileAppender 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, which is located in <APACHDS_HOME>/conf/, looks like.
The name of the RollingFileAppender is "R":
log4j.rootCategory=WARN, stdout, R
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-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
In this file "R" is configured like this:
Property name |
Value in file above |
Meaning |
|---|---|---|
File |
apacheds-rolling.log |
path to the output log file, in our case relative to var/log |
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.
Adjusting logging to your needs
Log file location (where the log files are placed)
By default the log files are placed at <APACHDS_HOME>/var/log/, but that can be changed.
Linux/MacOS/Solaris
On this systems the location of the log files is configured via an entry in /bin/server.init. Look for the following lines and change it to your preferences:
$DAEMON_HOME/apacheds \ ... -outfile $SERVER_HOME/var/log/apacheds-stdout.log \ -errfile $SERVER_HOME/var/log/apacheds-stderr.log \ ... $APACHEDS_HOME start
Windows
On Windows you can use the configuration wizard for the service as shown in the screenshot above. To adjust the log path you have to adjust the values of Redirect Stdout and Redirect Stderror
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
log4j.rootCategory=DEBUG, stdout, R ...
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:
... # 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
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.
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
...
log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n
...
Some examples lines within the log file, formatted with the pattern "[%d{HH:mm:ss}] %p [%c] - %m%n" are:
...
[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
...
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 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
log4j.appender.R.layout.ConversionPattern=[%d{dd.MM.yyyy HH:mm:ss}] %p: %c{1}.%M() - %m%n
leads to messages of this form:
...
[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
...
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)
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.
Learn more about log4j and related tools at its homepage.
Example configurations
The following example could be used to log all incoming search, add, delete, modify and moddn requests:
log4j.logger.org.apache.directory.server.ldap.handlers.SearchHandler=DEBUG log4j.logger.org.apache.directory.server.ldap.handlers.AddHandler=DEBUG log4j.logger.org.apache.directory.server.ldap.handlers.DeleteHandler=DEBUG log4j.logger.org.apache.directory.server.ldap.handlers.ModifyHandler=DEBUG log4j.logger.org.apache.directory.server.ldap.handlers.ModifyDnHandler=DEBUG
Log settings of the Windows daemon process
After installation on Windows, you have the option to configure the ApacheDS Windows Service (you can do this later as well). If you do so, one option pane is dedicated to logging:
You can adjust the logging level and a log path. Note that this is for the daemon only. The server itself is configured as described above.