| Title: 1.4.4 - Configure logging |
| NavPrev: 1.4.3-adding-partition.html |
| NavprevText: 1.4.3 - Adding your own partition |
| NavUp: 1.4-basic-configuration-tasks.html |
| NavUpText: 1.4 - Basic configuration tasks |
| NavNext: 1.4.5-anonymous-access.html |
| NavNextText: 1.4.5 - Enable and disable anonymous access |
| Notice: Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| . |
| http://www.apache.org/licenses/LICENSE-2.0 |
| . |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| # 1.4.4 - 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. |
| |
| [TOC] |
| |
| ## ApacheDS and logging |
| |
| ApacheDS 2.0 uses [SLF4J](http://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/). |
| |
| ## Default behavior after installation |
| |
| By default, ApacheDS writes log files in the directory _<APACHEDS_HOME>/var/log/_. Besides stdout, a [RollingFileAppender](http://logging.apache.org/log4j/docs/api/org/apache/log4j/RollingFileAppender.html) 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 _<APACHEDS_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 inundated 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 _<APACHEDS_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 inundated 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](http://logging.apache.org/log4j/docs/manual.html). |
| |
| ### 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 | Output | |
| |:-:|---| |
| | %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) 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 |
| ... |
| |
| <DIV class="warning" markdown="1"> |
| ** 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) |
| </DIV> |
| |
| ### 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). |
| |
| Learn more about log4j and related tools at its [homepage](http://logging.apache.org/log4j/docs/index.html). |
| |
| ## 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 service |
| |
| To run as a Windows service, the ApacheDS Java classes must be executed within a Windows native binary. The ApacheDS project relies on the Tanuki Software Java Service Wrapper's wrapper.exe to manage the ApacheDS Java Virtual Machine (JVM) process. While the ApacheDS Java code's logging is log4j-based, the wrapper.exe Windows service has its own logging configuration. For example, the wrapper.conf log settings govern the destination of the JVM's stdout and stderr logging and the logging of the communication between the wrapper.exe Windows service container and the JVM it hosts. |
| |
| An ApacheDS installation's wrapper.exe log settings are stored in: |
| |
| C:\Program Files (x86)\ApacheDS\conf\wrapper.conf. |
| |
| The Tanuki Software Java Service Wrapper web site documents all configuration settings for wrapper.exe including logging: |
| |
| https://wrapper.tanukisoftware.com/doc/english/introduction.html#logging |
| |
| ## Resources |
| |
| * [Short introduction to log4j](http://logging.apache.org/log4j/docs/manual.html) |
| |
| |
