Skip Navigation Links | |
Exit Print View | |
Oracle Directory Server Enterprise Edition Developer's Guide 11 g Release 1 (11.1.1.5.0) |
Part I Directory Server Plug-In API Guide
1. Before You Start Writing Plug-Ins
2. Changes to the Plug-In API Since Directory Server 5.2
3. Getting Started With Directory Server Plug-Ins
Updating Directory Server Configuration
Writing Directory Server Plug-Ins
Include the slapi-plugin.h Header File
Write an Initialization Function
Set Configuration Information Through the Parameter Block
Specifying the Plug-In Description
Set Pointers to Functions Through the Parameter Block
Building Directory Server Plug-Ins
Include the Header File for the Plug-In API
Link the Plug-In as a Shared Object or Dynamic Link Library
Locate the Example Build Rules
Plugging Libraries Into Directory Server
Specify Plug-In Configuration Settings
Understanding Plug-In Types and Dependencies
Retrieving Arguments Passed to Plug-Ins
Modify the Directory Server Configuration
Log Three Levels of Message Severity
Set the Appropriate Log Level in the Directory Server Configuration
4. Working With Entries Using Plug-Ins
5. Extending Client Request Handling Using Plug-Ins
6. Handling Authentication Using Plug-Ins
7. Performing Internal Operations With Plug-Ins
8. Writing Entry Store and Entry Fetch Plug-Ins
9. Writing Extended Operation Plug-Ins
10. Writing Matching Rule Plug-Ins
11. Writing Password Storage Scheme Plug-Ins
12. Writing Password Quality Check Plug-Ins
13. Writing Computed Attribute Plug-Ins
Part II Directory Server Plug-In API Reference
14. Data Type and Structure Reference
15. Function Reference, Part I
16. Function Reference, Part II
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.
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.
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.
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; }
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.