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
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.
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 16, Function Reference, Part I for details about each of the logging functions.
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.
#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.
If the plug-ins are internationalized, use macros, not literal strings, for the last two arguments to slapi_log_*_ex() functions.
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.
#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; }
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.
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.
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.