Introduction

When writting extensions to the openSSO policy server like a post authentication processor or custom policy conditions such extensions can participate in the debug infrastructure provided by openSSO. The provided infrastructure consists of a policy server administration console panel for activating server wide debug level, a debug java server page that can activate server wide debug level logging on a selective portion of the policy server including just your extension classes, and a java API used by the policy server code and your extensions for logging varying levels of events.

Activating Server Wide Debugging

After logging into the Enterprise 8.0 policy server as an administrator select the Configuration tab, Servers and Sites sub-tab, and select a server link. Scrolling downward you'll fine a Debugging section with two fields: Debug Level and Merge Debug Files. The Debug Level has four values:

The Merge Debug Files field when turned on causes all log entries to be written to a single debug.out file. This can be very useful when things go wrong with the server and you are uncertain which portion of the server is as fault. When this field is set to Off log entries will be written to separate files.

Depending on your configuration turning on server wide debugging can generate copious log entries particularly for the IdRepo in my case. I do this only when necessary and prior to activating it I set up the scenario immediately preceding the action that causes a failure. Then I turn it on, perform the action, turn it off, and then go look at the debug.out.

Activating Server Wide Category (Component) Debugging

After logging into the Enterprise 8.0 policy server as an administrator enter the following URL into your browser with suitable host, port, and base uri.

This page shows the set of registered "categories" whose debug level can selectively be activated. These categories really are groupings of named instances of Debug objects. (See the Debug Java API below.) The groupings are completely arbitrary based upon entries in two properties files located in <opensso-web-app-root>/WEB-INF/classes. Upon editing either of these files the server must be bounced to cause these changes to be reloaded. Another shortcut is to execute "touch" on one of the jar files in WEB-INF/lib if your servlet container supports automatic reloading of the application which is typically much faster than restarting the whole servlet container.

To activate a selective debug level for a category select the category in the Category drop down selection list followed by the desired debug level in the Level drop down selection list and press the Submit button. A confirmation page is presented indicating the category and listing each of the named Debug instances whose debug level will be set. Pressing the Confirm button then activates debugging at that level.

This will only activate debugging on the server which receives the Confirm http request. If you are using clustering of your policy servers you will need to be certain which server in the cluster is being told to adjust its debug level and look on that server for the corresponding log file entries.

Debug Java API

The debugging API provided by openSSO is found in the com.sun.identity.shared.debug.Debug class located in the sharedlib-8.0.jar file. This API has constructs and concepts similar to most debug libraries. You craete a named instance by importing this class can calling its get instance method. Calls for the different levels of debug message can then be made using the correspondingly named method.

package org.lds.policy;

import com.sun.identity.policy.ConditionDecision;
import com.sun.identity.policy.PolicyException;
import com.sun.identity.policy.interfaces.Condition
import com.sun.identity.shared.debug.Debug;

public class ConditionOne implements Condition {
    protected static Debug cLog = Debug.getInstance(ConditionOne.class.getName());

    public ConditionDecision getConditionDecision(SSOToken token, Map env) throws PolicyException {

        ... // log various debug entries
        cLog.message("some message"); // OR
        cLog.message("some message", exceptionObj); // OR
        cLog.warning("some message"); // OR
        cLog.warning("some message", exceptionObj); // OR
        cLog.error("some message"); // OR
        cLog.error("some message", exceptionObj); // OR

        ...// optionally check before forcing string concatenation that won't get logged
        if (cLog.messageEnabled()) {
            cLog.message("some" + " multi-part" + " message");
        }
    }
...
}

Log File Location and Names

The log files into which entries are written are located a debug directory within a directory representing the opensso instance's base uri which is itself located within the openSSO configuration directory. If my installation specified an installation directory of "/opt/opensso" for an opensso instance with a base uri of "opensso", then the debug directory is found at "/opt/opensso/opensso/debug".

Debug file names depend upon if you have defined categories in debug.properties and debugfiles.properties. (See Activating Server Wide Category (Component) Debugging above.) If the Debug instance name has not been declared as part of a category then log entries made by that instance will be written to a file having the same name as the instance if server wide debugging has not been activated with Merge Debug Files set to On. If the instance has been declared as part of a category then log entries will be written to a file having the name of the category.

For example, given the additions to the debug properties files the ConditionOne entries will be written to the file
LDS-Plugins file located in /opt/opensso/opensso/debug.