Sun OpenSSO Enterprise 8.0 Developer's Guide

Using the Logging Interfaces

The Logging Service contains both an application programming interface (API) and service provider interface (SPI). You can use the logging APIs to add logging functionality to a client application and the SPIs to develop custom plug-ins to add functionality to the Logging Service.

Implementing Logging with the Logging Service API

The Logging Service API provides the interfaces for the OpenSSO Enterprise internal services and remote applications running the Client SDK to create and submit log records. Retrieving log records cannot be done using the client SDK. The logging API is in the com.sun.identity.log package, which is documented in the Sun OpenSSO Enterprise 8.0 Java API Reference.

The Logging Service API extends the core logging APIs in the Java SE. For more information about the Java SE APIs, see

The following sections have more information.

For more information see the Sun OpenSSO Enterprise 8.0 Java API Reference.

Writing Log Records

When writing log records, the Logging Service verifies that the logging requester has the proper authority to log and then writes the information to the configured location, formatting and completing the columns in the log records.

An application makes logging calls using the getLogger() method, which returns a Logger object. Each Logger keeps track of a log level and discards log requests that are below this level. (There is one Logger object per log file.) The applications allocates a LogRecord, which is written to the log file using the log() method. An SSOToken, representing the user's session data, is passed to the LogRecord constructor and used to populate the appropriate fields to be logged.

OpenSSO Enterprise contains plug-ins to write log records to:

The Logging Service requires two session tokens:

Note –

If your application also invokes utilities that log without using the OpenSSO Logging Service API, then you might also need to include the following:

import com.sun.identity.log.Logger;

where ssoToken is the SSOToken of the entity requesting the logging. Also, once done, the following statement should be executed:

Logger.token.set(null); to clear the entity's SSOToken from the Logging Service.

The following parameters can have values logged when the addLogInfo() method is invoked. All columns except for time, Data, and NameID can be selected for exclusion from the record written to the log file.


The date and time is retrieved from OpenSSO Enterprise and added by the Logging Service.


The event being logged as defined in the message string specified in the LogRecord() constructor call.


The value specified for the LogConstants.MODULE_NAME property in the addLogInfo() call. For example, the RADIUS module might be specified in an authentication attempt.

Note –

If no value is specified, this field will be logged as Not Available.


The value specified for the LogConstants.MESSAGE_ID property in an addLogInfo() call.

Note –

If no value is specified, this field will be logged as Not Available.


The value for this field is extracted from the SSOToken and corresponds to either the subject userID's domain, or organization.


The value for this field is extracted from the SSOToken and corresponds to the subject userID's session context.


The logging level, passed to the LogRecord() constructor, at which this record is being logged.


The value for this field is extracted from the SSOToken and corresponds to the subject userID's Principal name.


The value specified for the LogConstants.NAME_ID property in an addLogInfo() call. It is an alias that maps to the actual userID.

Note –

If no value is specified, this field will be logged as Not Available.


The value for this field is extracted from the SSOToken and corresponds to the originating point of the action being logged.


The identifier in this field is extracted from the logging requestor's SSOToken specified in the Logger.log() call.


The host name corresponding to the originating point of the action being logged is derived from the IPAddr in the user's SSOToken, if it can be resolved.

Note –

Resolving host names is disabled by default; enable this feature by toggling the Log Record Resolve Host Name system configuration attribute under Logging Service. If disabled, the HostName value is taken from the user's SSOToken and the IPAddr value is logged as Not Available.

Reading Log Records

When handling log reading requests, a valid SSOToken must be provided. The Logging Service verifies that the requester has the proper authority, and then it retrieves the requested records from the configured log location. The LogReader class provides the mechanism to read a log file and return the appropriate data to the caller. It provides the authorization check, reads the data, applies the query (if any), and returns the result as a string. The LogQuery is constructed using the getLogQuery() method.

Note –

Reading log records from a remote client program using the client SDK is not supported.

Unless all records from a log file are to be retrieved, at least one LogQuery must be constructed. The LogQuery objects qualify the search criteria.

A LogQuery can specify a list of QueryElements, each containing a value for a field (column) and a relationship. The QueryElement supports the following relationships:


Greater than


Less than


Equal to


Not equal to


Greater than or equal to


Less than or equal to




Starts with


Ends with

Caution – Caution –

Log files and tables in particular can become very large. If you specify multiple logs in a single query, create queries that are very specific or limited in the number of records to return (or both specific and limited). If a large number of records are returned, the OpenSSO Enterprise resource limits (including those of the host system) can be exceeded.

The following sample code queries for all successful authentications in realm dc=example,dc=com, and returns the time, Data, MessageID, ContextID, LoginID, and Domain fields, sorted on the LoginID field:

ArrayList al = new ArrayList();
al.add (LogConstants.TIME);
al.add (LogConstants.Data);
al.add (LogConstants.MESSAGE_ID);
al.add (LogConstants.CONTEXT_ID);
al.add (LogConstants.LOGIN_ID);
al.add (LogConstants.DOMAIN);
LogQuery lq = new LogQuery(LogQuery.ALL_RECORDS,

QueryElement qe1 = new QueryElement(LogConstants.MESSAGE_ID,

QueryElement qe2 = new QueryElement(LogConstants.DOMAIN,

In this code, assuming that dc=example,dc=com is the root realm, changing the qe2 relationship field to QueryElement.EW or QueryElement.CN changes the query to include all successful authentications in all realms. To read the example query from the amAuthentication.access log, assuming presence of an SSOToken, add the following:

 String[][] result = new String[1][1];
    result = read("amAuthentication.access", lq, ssoToken);

The first record in a log (row 0) contains the field and column names.