Configuring Logs With the Log Publisher

Oracle Unified Directory provides several types of logs: access logs, audit logs, error logs, debug logs, and a replication repair log. The replication repair log is read-only and its use is restricted to enabling replication conflict resolution. This section describes how to use dsconfig to configure access, audit, error, and debug logs.

Log Configuration Overview

The easiest way to configure logging is to use the dsconfig command in interactive mode, which walks you through the configuration. This section provides the required commands in non-interactive mode. For more information about dsconfig, see Managing the Server Configuration With dsconfig.

Log configuration includes the definition of three configuration objects:

• Log publisher. A log publisher is defined for each logger. The log publisher type corresponds to the type of log. For more information about log publishers, see Configuring Log Publishers.

• Log retention policy. The retention policy determines how long archived log files are stored. For more information about log retention policies, see Configuring Log Retention Policies.

• Log rotation policy. The rotation policy determines how often log files are rotated. For more information on log rotation policies, see Configuring Log Rotation Policies.

Configuring Log Publishers

Oracle Unified Directory provides several log publishers by default.

Any number of log publishers of any type can be defined and active at any time. This means that you can log to different locations or different types of repositories and that you can specify various sets of criteria for what to include in the logs.

For more information about the configuration properties associated with log publishers, see the Oracle Unified Directory Configuration Reference..

Oracle Unified Directory can also write diagnostic log files in the Oracle Diagnostic Logging (ODL) format. ODL is disabled by default. To enable ODL, set the enabled property of the ODL Access Log publisher or the ODL Error Log publisher to true, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \ 
  set-log-publisher-prop --publisher-name "Oracle Access Logger" --set enabled:true

To List Existing Log Publishers

1. To view the existing log publishers run the following dsconfig command:

   $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \
     list-log-publishers 

   The default output will be similar to the following:

   Log Publisher             : Type              : enabled
   --------------------------:-------------------:--------
   File-Based Access Logger  : file-based-access : true
   File-Based Audit Logger   : file-based-access : false
   File-Based Debug Logger   : file-based-debug  : false
   File-Based Error Logger   : file-based-error  : true
   Oracle Access Logger      : file-based-access : false
   Oracle Error Logger       : file-based-error  : false
   Replication Repair Logger : file-based-error  : true

2. (Optional) To display the properties of a log publisher run the following dsconfig command:

   $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \
     get-log-publisher-prop --publisher-name "File-Based Error Logger"

Logging Internal Operations

By default, the suppress-internal-logging property for log publishers is set to true. If you need to log internal operations (such as operations performed by the LDIF connection handler and certain plug-ins), set suppress-internal-logging to false. The following example sets suppress-internal-logging to false for the file-based access logger:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
  set-log-publisher-prop \
  --advanced --publisher-name "File-Based Access Logger" \
  --set suppress-internal-operations:false

Configuring Log Retention Policies

Log retention policies dictate size and space limits for log files. Oracle Unified Directory provides the following three log retention policies:

• File count retention (file-count). By default, this policy sets the maximum number of log files to 10, for a specified type of log file.

• Free disk space retention (free-disk-space). By default, this policy sets a minimum remaining free disk space limit to 500 Mb, for a specified type of log file.

• Size limit retention (size-limit). By default, this policy sets the disk spaced used to a maximum of 500 Mb, for a specified type of log file.

By default, the log retention policy that is enabled is File count retention.

You can also create your own custom log retention policies.

To View the Log Retention Policies

1. To view a list of the existing log retention policies run the following dsconfig command:

   $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \
     list-log-retention-policies 

   The default output will be similar to the following:

   Log Retention Policy             : Type            : disk-space-used : free-disk-space : number-of-files
   ---------------------------------:-----------------:-----------------:-----------------:----------------
   File Count Retention Policy      : file-count      : -               : -               : 10
   Free Disk Space Retention Policy : free-disk-space : -               : 500 mb          : -
   Size Limit Retention Policy      : size-limit      : 500 mb          : -               : - 

2. (Optional) To list the log retention policy properties run the following dsconfig command

   $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \
   get-log-retention-policy-prop --policy-name "Free Disk Space Retention Policy"

To Create a Log Retention Policy

• To create a log retention policy, and to set it as enabled, type:

  $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n 
  create-log-retention-policy \
  --policy-name MyMaxDiskSpace \
  --type size-limit \
  --set disk-space-used:100mb

To Modify a Log Retention Policy

• To modify the properties of an existing log retention policy run the following dsconfig command:

  $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n 
  set-log-retention-policy-prop \
  --policy-name "File Count Retention Policy" \
  --set number-of-files:20

  Instead of setting a property value, you can add, reset or remove a property value, using the --add, --reset, or --remove subcommands instead of the --set subcommand. For details, see dsconfig in Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory.

Configuring Log Rotation Policies

Log rotation policies dictate how often the files are rotated, that is to say, how long log files are kept based on various criteria. Oracle Unified Directory provides the following four log rotation policies:

• 24 Hours time limit rotation policy. By default, this policy sets the rotation interval to one day. Time of day can be configured.

• 7 Days time limit rotation policy. By default, this policy sets the rotation interval to one week. Time of day can be configured.

• Fixed time limit rotation policy. By default, this policy sets the time of day that log files are to be rotated, to one minute before midnight.

• Size time limit rotation policy. By default, this policy sets a maximum size that log files can reach to 100 Mb, before the log file is rotated.

The type of log rotation policy enabled by default depends on the log type.

• For access and audit logs, the following are enabled:

  • 24 Hours time limit rotation policy

  • Size time limit rotation policy

• For error and replication repair logs, the following are enabled:

  • 7 Days time limit rotation policy

  • Size time limit rotation policy

You can create your own custom log rotation policies.

To View the Log Rotation Policies

1. To view a list of the existing log rotation policies run the following dsconfig command:

   $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \
   list-log-rotation-policies 

   The default output will be similar to the following:

   Log Rotation Policy                 : Type       : file-size-limit : rotation-interval : time-of-day
   ------------------------------------:------------:-----------------:-------------------:------------
   24 Hours Time Limit Rotation Policy : time-limit : -               : 1 d               : -
   7 Days Time Limit Rotation Policy   : time-limit : -               : 1 w               : -
   Fixed Time Rotation Policy          : fixed-time : -               : -                 : 2359
   Size Limit Rotation Policy          : size-limit : 100 mb          : -                 : - 

2. (Optional) To list the log rotation policy properties, type

   $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n \
   get-log-rotation-policy-prop "Fixed Time Rotation Policy"

To Create a Log Rotation Policy

• To create a log rotation policy run the following dsconfig command:

  $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password -X -n 
  create-log-rotation-policy \
  --policy-name my2DayPolicy \
  --type time-limit \
  --set rotation-interval:2d

  The policy type can be one of the following:

  • size-limit

  • fixed-time

  • time-limit

To Set Log Rotation or Retention for a Specific Log File

In order to set a log rotation policy on a specific log file, you must create a log publisher and set the log rotation or log retention policy.

• To set log rotation or retention for a specific log file run the following dsconfig command:

  $ dsconfig -h localhost -p 1444 -D "cn=Directoy manager" -w password -n -X \
  create-log-publisher \
  --publisher-name myPublisher \
  --type file-based-access \
  --set log-file:logs/myLogs \
  --set enabled:true \
  --set retention-policy:MyMaxDiskSpace \
  --set rotation-policy:my2DayPolicy

Differences Between Logging in Oracle Unified Directory and Oracle Directory Server Enterprise Edition

The logging architectures of Oracle Unified Directory and Oracle Directory Server Enterprise Edition differ significantly. The most notable differences include the following:

• Oracle Unified Directory allows for several loggers of any type to be defined and active at any time. This feature makes it possible to log messages to different locations and to different types of repositories. You can also define different sets of criteria for what to include in the logs. For example, one access log might hold everything, another might hold operations with a non-zero result code only, and yet another might hold write operations only.

• Oracle Directory Server Enterprise Edition defines an audit logger that is used to hold information about the changes that are made to directory data. In Oracle Unified Directory, the audit logging capability is still present, but it is classified as a type of access logger.