UnboundID Server SDK

Ping Identity
UnboundID Server SDK Documentation
Getting Started with the UnboundID Server SDK

Logging, Debugging, and Alerting

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:

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.

Accessing Server SDK Extension Debug Messages

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

Logging from within Command Line Tools

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.