UnboundID Server SDK
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 ServerContext class,
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
{server‑root}/logs/tools/{tool‑name}.debug.
The logging verbosity and scope is configurable via a couple of special options on
the command line. See the ‑‑help‑debug argument
on any of the command line tools for more information.