Logging Plug-In Messages

This sectioon shows how to do the following:

Generate messages in the Directory Server logs
Set the log level such that Directory Server writes particular types of messages to the log
Find the messages that the server has logged

Log Three Levels of Message Severity

The plug-in API provides log functions for logging fatal error messages, warnings, and information. Error messages and warnings are always logged. Informational logging is turned off by default. You can adjust log levels while Directory Server is running.

Tip - Directory Server, as Directory Server waits for the system to write every log message to disk, slowing the server down.

Use logging when you need logging. Turn logging off when you do not need to use it.

Refer to Chapter 15, Function Reference, Part I for details about each of the logging functions.

Fatal Error Messages

For fatal errors, use slapi_log_error_ex(). In many cases, you might return -1 after you log the message to indicate to Directory Server that a serious problem has occurred.

Example 3-5 Logging a Fatal Error Message

#include "slapi-plugin.h"
#include "example-com-error-ids.h" /* example.com unique
                                      error IDs file       */
int
foobar(Slapi_PBlock * pb)
{
    char * error_cause;
    int    apocalypse = 1;         /* Expect the worst.    */

    /* ... */

    if (apocalypse) {              /* Server to crash soon */
        slapi_log_error_ex(
            EXCOM_SERVER_MORIBUND, /* Unique error ID      */
            SLAPI_LOG_NO_MSGID,
            SLAPI_LOG_NO_CONNID,
            SLAPI_LOG_NO_OPID,
            "example.com: foobar in baz plug-in",
            "cannot write to file system: %s\n",
            error_cause
        );
        return -1;
    }
    return 0;
}

In this example, foobar() logs an error as Directory Server is about to crash.

Tip - If the plug-ins are internationalized, use macros, not literal strings, for the last two arguments to slapi_log_*_ex() functions.

Warning Messages

For serious situations that require attention and in which messages should always be logged, use slapi_log_warning_ex().

In the following example, foobar() logs a warning because the disk is nearly full.

Example 3-6 Logging a Warning Message

#include "slapi-plugin.h"
#include "example-com-warning-ids.h" /* example.com unique
                                        warning IDs file  */
int
foobar()
{
    int disk_use_percentage;

    /* ... */

    if (disk_use_percentage >= 95) {
        slapi_log_warning_ex(
            EXCOM_DISK_FULL_WARN,    /* unique warning ID */
            SLAPI_LOG_NO_MSGID,
            SLAPI_LOG_NO_CONNID,
            SLAPI_LOG_NO_OPID,
            "example.com: foobar in baz plug-in",
            "disk %.0f%% full, find more space\n",
            disk_use_percentage
        );
    }
    return 0;
}

Informational Messages

For informational or debug messages, use slapi_log_info_ex(). This function can be set for default logging, which means that the message is not logged when logging is turned off for plug-ins. Informational logging can also be set to occur only when heavy logging is used. Thus, the message is logged when plug-in logging is both turned on and set to log all informational messages.

Refer to Review the Plug-In for an example of how to log an informational message from a plug-in.

Set the Appropriate Log Level in the Directory Server Configuration

Log levels can be set for plug-in informational messages, as well as for a number of other Directory Server subsystems. You can set the log level through Directory Service Control Center. You can also set the log level from the command line by using the dsconf set-log-prop command.

When you set dsconf set-log-prop error level:err-plugins, the server turns on plug-in informational logging.

Find Messages in the Log

The log file for errors, warnings, and informational messages is instance-path/logs/errors. All messages go to the same log so you can easily determine the order in which events occurred.

As shown in this example, messages consist of a timestamp, followed by an identifier, followed by the other information in the log message. Note that this log message is broken for the printed page.

[02/Jan/2006:16:54:57 +0100] - INFORMATION - 
 start_tls - conn=-1 op=-1 msgId=-1 - 
 Start TLS extended operation request confirmed.

Use the identifiers to filter what you do not need.

Skip Navigation Links
Exit Print View
	Oracle Directory Server Enterprise Edition Developer's Guide 11 g Release 1 (11.1.1.5.0)