Chapter 5 Tuning Logging

Chapter 5
Tuning Logging

Directory Server provides several log types, summarized in Table 5-1. This chapter discusses how to handle the different types of logs.

Table 5-1 Types of Logs Used by Directory Server
Log	Type	Use
Access	Flat file	Evaluating directory use patterns, verifying configuration settings, diagnosing access problems. Refer to Access Logging for details.
Audit	Flat file	Providing audit trails for security and data integrity. Refer to Audit Logging for details.
Changelog	Database	Enables synchronization between replicas. Refer to Multi-Master Replication Change Logging for details.
Error	Flat file	Debugging directory deployments. Refer to Error Logging for details.
Retro changelog	Database	Permitting backward compatibility with previous versions. Refer to Retro Change Logging for details.
Transaction	Database	Maintaining database integrity. Refer to Transaction Logging for details.

In high-volume deployments, writing to logs can be disk intensive, resulting in noticeable negative performance impact. Given the potential for I/O bottlenecks inherent with heavy logging in high volume systems, consider putting log files on a lesser used disk.

Access Logging

The access log contains detailed information about client connections and operations performed. The access log can be indispensable when diagnosing access problems, verifying server configuration settings, and evaluating server usage patterns.

Although the access log provides beneficial troubleshooting information, it may become an I/O bottleneck. Set access logging levels to the minimum required level. Table 5-2 provides further recommendations for specific attributes.

Table 5-2 Tuning Recommendations for Access Logging
Configuration Attribute	Short Description and Tuning Recommendations
dn: cn=config nsslapd-accesslog	Specifies the path and filename of the access log file. In most deployments, the access log may share a disk with the audit and error logs, and the replication changelog.
dn: cn=config nsslapd-accesslog-level	Specifies the level of informational logging used. Leave at default (256) unless a higher level is required.
dn: cn=config nsslapd-accesslog-logbuffering	Determines whether the access log is buffered. Leave on (default) unless you must disable buffering to see access log messages as they are triggered. Disabling buffering can result in a drop in overall performance.
dn: cn=config nsslapd-accesslog-logging-enabled	Enables and disables access logging. Set nsslapd-accesslog-level to the lowest acceptable setting. Rotate the access log frequently (each day or week) and use nsslapd-accesslog-logmaxdiskspace and nsslapd-accesslog-logminfreediskspace to manage disk space use.
dn: cn=config nsslapd-accesslog-logmaxdiskspace	Specifies maximum disk space in MB that all access logs (current and rotated logs) may consume. Set this value below the total amount of disk space dedicated to access logging, leaving space for other logs on the disk.
dn: cn=config nsslapd-accesslog-logminfreediskspace	Specifies minimum free disk space in MB allowed before old logs are purged. When the amount of free disk space falls below the value specified on this attribute, the oldest access logs are deleted until enough disk space is freed to correspond to the setting for this attribute. If the access logs cannot be written because the disk is full, the server shuts down.

Refer to the Directory Server Administration Reference for details concerning individual configuration attributes.

The Directory Server Resource Kit Tools Reference covers extracting information from the access log.

Audit Logging

The audit log contains detailed information about all changes made to each database as well as to server configuration. Audit logging is disabled by default.

When enabled in deployments having high modify volume, enabling audit logging causes a very noticeable overall drop in performance. Unless the deployment requires it, leave audit logging disabled. For large or high volume deployments that require audit logging, consider allocating a separate disk on a separate controller to the audit log. Table 5-3 provides further recommendations for specific attributes.

Table 5-3 Tuning Recommendations for Audit Logging
Configuration Attribute	Short Description and Tuning Recommendations
dn: cn=config nsslapd-auditlog	Specifies the path and filename of the audit log file. In most deployments, the audit log may share a disk with the access and error logs, and the replication changelog.
dn: cn=config nsslapd-auditlog-logging-enabled	Enables and disables audit logging. Leave off (default setting) unless audit logging is required.
dn: cn=config nsslapd-auditlog-logmaxdiskspace	Specifies maximum disk space in MB that all audit logs (current and rotated logs) may consume. Set this value below the total amount of disk space dedicated to audit logging, leaving space for other logs on the disk.
dn: cn=config nsslapd-auditlog-logminfreediskspace	Specifies minimum free disk space in MB allowed before old logs are purged. When the amount of free disk space falls below the value specified on this attribute, the oldest audit logs are deleted until enough disk space is freed to correspond to the setting for this attribute. If the audit logs cannot be written because the disk is full, the server shuts down.

Refer to the Directory Server Administration Reference for details concerning individual configuration attributes.

Error Logging

The error log for a Directory Server instance contains detailed error, warning, and informational messages encountered during normal server operation. The low default logging level produces relatively little disk activity.

When log level is set higher to generate debugging information, however, Directory Server may begin writing large numbers of messages to disk. The write load can result in a very noticeable overall drop in performance. To avoid a drop in performance, increase log levels progressively, component by component, instead of activating log levels for all components at once.

The error log does not support log buffering. All messages are flushed to disk immediately. Table 5-4 provides recommendations for specific attributes.

Table 5-4 Tuning Recommendations for Error Logging
Configuration Attribute	Short Description and Tuning Recommendations
dn: cn=config nsslapd-errorlog	Specifies the path and filename of the error log file. In most deployments, the error log may share a disk with the access and audit logs, and the replication changelog.
dn: cn=config nsslapd-errorlog-logging-enabled	Enables and disables error logging. Leave on (default setting).
dn: cn=config nsslapd-errorlog-logmaxdiskspace	Specifies maximum disk space in MB that all error logs (current and rotated logs) may consume. Set this value below the total amount of disk space dedicated to error logging, leaving space for other logs on the disk.
dn: cn=config nsslapd-errorlog-logminfreediskspace	Specifies minimum free disk space in MB allowed before old logs are purged. When the amount of free disk space falls below the value specified on this attribute, the oldest error logs are deleted until enough disk space is freed to correspond to the setting for this attribute. If the error logs cannot be written because the disk is full, the server shuts down.
dn: cn=config nsslapd-infolog-area	Specifies the components for which informational messages are logged. Leave at 0 (default) unless debugging a component. Avoid setting for more than one component at a time on production servers.
dn: cn=config nsslapd-infolog-level	Specifies the level of informational logging used. Leave at 0 (default) unless debugging a component for which setting nsslapd-infolog-area alone fails to generate sufficient detail.

Refer to the Directory Server Administration Reference for details concerning individual configuration attributes.

Multi-Master Replication Change Logging

Directory Server uses a replication changelog to enable synchronization between replicas. Refer to the Directory Server Deployment Planning Guide for an discussion of the changelog and to the Directory Server Administration Reference for configuration details. Table 5-5 provides further recommendations for specific attributes.

Table 5-5 Tuning Recommendations for Multi-Master Change Logging
Configuration Attribute	Short Description and Tuning Recommendations
dn: cn=changelog5,cn=config nsslapd-cachememsize	Specifies the changelog database cache size. Consider changing this from the default of 10 MB for high volume deployments.
dn: cn=changelog5,cn=config nsslapd-changelogdir	Specifies the path of the changelog database. In most deployments, the replication changelog may share a disk with the access, audit, and error logs.
dn: cn=changelog5,cn=config nsslapd-changelogmaxage	Specifies the maximum age for entries in the changelog. Refer to the Directory Server Administration Reference for details on the syntax. Change this from 0 (default, indicating no maximum) to an interval after which replicated servers are fully synchronized and the changelog may be trimmed.
dn: cn=changelog5,cn=config nsslapd-changelogmaxentries	Specifies the maximum number of entries in the changelog. Change this from 0 (default, indicating no maximum) to a number sufficient to allow replicated servers to become fully synchronized before the changelog is trimmed.

Refer to the Directory Server Administration Reference for details concerning individual configuration attributes.

Retro Change Logging

Directory Server ships with a retro changelog plug-in that you may enable to record changes on a supplier server in a format compatible with Directory Server 4.x releases and accessible through LDAP. The retro changelog plug-in is disabled by default and should not be enabled unless required for compatibility reasons. Refer to the Directory Server Administration Reference for details. Table 5-6 provides further recommendations for specific attributes.

Table 5-6 Tuning Recommendations for Retro Change Logging
Configuration Attribute	Short Description and Tuning Recommendations
dn: cn=Retro Changelog Plugin,cn=plugins,cn=config nsslapd-changelogdir	Specifies the path of the retro changelog. In most deployments, the retro changelog may share a disk with the access, audit, and error logs.
dn: cn=Retro Changelog Plugin,cn=plugins,cn=config nsslapd-changelogmaxage	Specifies the maximum age for entries in the retro changelog. Refer to the Directory Server Administration Reference for details on the syntax. Change this from 0 (default, indicating no maximum) to an interval after which clients using the retro changelog have processed the log entries generated.
dn: cn=Retro Changelog Plugin,cn=plugins,cn=config nsslapd-changelogmaxentries	Specifies the maximum number of entries in the retro changelog. Change this from 0 (default, indicating no maximum) to a maximum number of entries retained in the retro changelog before trimming.

Refer to the Directory Server Administration Reference for details concerning individual configuration attributes.

Transaction Logging

Directory Server maintains database integrity through transaction logging. Upon accepting an update operation — add, modify, delete, or modrdn — Directory Server writes a log message about the operation to the transaction log. Durable transaction logging, enabled by default, ensures data integrity. It does so by ensuring each update operation is committed to the transaction log on disk before the result code for the update operation is returned to the client application. In the event of a system crash, Directory Server uses the transaction log to recover the database. As the transaction log aids in the recovery of a database shut down abnormally, consider storing the transaction log and directory database on separate disk subsystems.

Table 5-7 provides recommendations for specific attributes.

Table 5-7 Tuning Recommendations for Transaction Logging
Configuration Entry DN and Configuration Attribute	Short Description and Tuning Recommendations
dn: cn=config,cn=ldbm database,cn=plugins,cn=config nsslapd-db-checkpoint-interval	Specifies how often Directory Server checkpoints the transaction log, ensures the entire database system is synchronized to disk, and cleans up transaction logs. Leave at 60 (default interval in seconds) unless database performance optimization based on empirical testing calls for a different value. Increasing the value of this attribute may result in a performance boost for update operations, but also means that recovery after disorderly shutdown takes longer, and that the transaction log uses more disk space.
dn: cn=config,cn=ldbm database,cn=plugins,cn=config nsslapd-db-durable-transaction	Specifies whether update operations are committed to the transaction log on disk before result codes are sent to clients. Leave on (default) for deployments requiring a high level of data integrity. Rather than disabling durable transaction logging to boost performance, first consider batching transactions using nsslapd-db-transaction-batch-val. When durability is disabled, log messages flushed to the file system but not yet to disk may be lost in the event of a system crash. This means that with durable transaction logging off, some updates may be unrecoverable even after the client receives a successful update result code.
dn: cn=config,cn=ldbm database,cn=plugins,cn=config nsslapd-db-logbuf-size	Specifies the buffer size for log information stored in memory until the buffer fills or the transaction commit forces the buffer to be written to disk. Leave at 524288 (512K, default). If you must change the value, do so before loading much data into the directory, then follow these steps: 1. Reduce the load on Directory Server. 2. Export all databases to LDIF. 3. Change the value of nsslapd-db-logbuf-size. 4. Stop Directory Server. 5. Delete files with names of the form __db.xxx and guardian in nsslapd-db-home-directory. 6. Import all databases from LDIF. 7. Start Directory Server. The value of this attribute must not exceed 25% of the transaction log file size, which by default is 10 MB. For a default configuration, therefore, this attribute should not exceed 2.5 MB in size.
dn: cn=config,cn=ldbm database,cn=plugins,cn=config nsslapd-db-logdirectory	Specifies the path of the transaction log. Consider storing the transaction log and directory database on separate disk subsystems.
dn: cn=config,cn=ldbm database,cn=plugins,cn=config nsslapd-db-transaction-batch-val	Specifies how many updates are batched before being committed to the directory database. Only change from 0 (no batching, default) if you can afford to lose updates in the event of a crash. If you can afford to lose updates in a crash, then setting this to attribute to a value such as 5 can potentially increase write performance significantly. In order for batching to work correctly, the maximum size of a batch of transactions must fit in the transaction log buffer. You may therefore need to increase the value of nsslapd-db-logbuf-size when changing the value of this attribute.

Refer to the Directory Server Administration Reference for details concerning individual configuration attributes.

Previous Contents Index Next

Previous Contents Index Next
Sun Java(TM) System Directory Server 5 2004Q2 Performance Tuning Guide