In order to help make it easier to support third-party extensions, the UnboundID
Server SDK provides methods for generating debug messages, writing messages to the
server error logging subsystem, and generating administrative alerts. All of
these capabilities are exposed through the
through the following methods:
logMessage– This method may be used to write log messages to the server's error logging subsystem. Both the log severity and the message text should be provided as arguments to this method.
sendAlert– This method may be used to cause the server to generate administrative alert notifications. There are actually two variants of this method: one that takes only a severity and a message, and another that can be used to specify additional details like the alert type name and OID.
debugEnabled– This method may be used to indicate whether debug logging is enabled in the server. For potentially-expensive debugging operations (e.g., messages constructed by concatenating several components), it is recommended that you check to see whether debugging is enabled before paying the cost of constructing the message.
debugCaught– This method may be used to indicate that an exception was caught within the extension itself and was either handled or re-thrown. It is recommended that you use this method to record information about any exceptions caught in your extension code.
debugThrown– This method may be used to indicate that your extension is about to throw a given exception. If you are going to create and throw a new exception in your extension, then it may be useful to use this method to record it in the debug logger to protect against the event that whatever catches it doesn't debug the caught exception.
debugError– This method may be used to write an arbitrary error message to the debug logging subsystem.
debugWarning– This method may be used to write an arbitrary warning message to the debug logging subsystem.
debugInfo– This method may be used to write an arbitrary informational message to the debug logging subsystem.
debugVerbose– This method may be used to write an arbitrary message to the debug logging subsystem with a "verbose" severity (meaning that it will only be visible to administrators that have turned on the highest level of debugging output).
As noted above, there are two variants of the
sendAlert method that
may be used to generate alert notifications. The first one takes only a severity
(INFO, WARNING, ERROR, or FATAL) and a message string, and it will use a generic
alert type depending on that severity (user‑defined‑info,
user‑defined‑warning, user‑defined‑error, or
user‑defined‑fatal), each of which has its own predefined OID.
However, if you want to use your own custom OID (e.g., for use in SNMP traps if
the SNMP alert handler is enabled), then you will need to use the second variant
which also requires that you provide an alert type name and OID. When using this
variant, you must be careful to ensure that each time you use a given alert type
name, you must use the same numeric OID, and that OID must not be used for any
other alert types.
Debug messages created by Server SDK extensions will be logged in the same way as other debug messages generated by other elements of the server. As such, simply enabling the default file-based debug log publisher will include debug messages generated by Server SDK extensions along with debug messages generated in other areas of the server.
However, if you wish to see only those debug messages generated by Server SDK
extensions, you can easily accomplish this with the Server SDK Extension Debug
Logger. This logger is configured so that by default, it will suppress all debug
messages generated in the server, and it has a debug target which overrides this
setting for only messages generated by Server SDK extensions (all messages
generated by Server SDK extensions will ultimately be written by the
com.unboundid.directory.sdk.impl.ServerContextImpl class in the
server, so a debug target with a scope set to that class value may be used to
customize the debug level that a debug logger will accept for messages generated
by Server SDK extensions). If you enable the Server SDK Extension Debug Logger,
then all debug messages written by Server SDK extensions will be written to the
logs/server‑sdk‑extension‑debug file. The Server
SDK Extension Debug Logger can be enabled using the following command:
dsconfig set-log-publisher-prop \ --publisher-name "Server SDK Extension Debug Logger" \ --set enabled:true
The same mechanisms described above, using
ServerContext, will also
work when a third-party extension or script is loaded in the context of a command
line tool. However, since this is outside of the Directory Server
process, the logging subsystem will write messages to a special file under
The logging verbosity and scope is configurable via a couple of special options on
the command line. See the
on any of the command line tools for more information.