HomeDownloadsUser GuideDevelopment

Architecture: Logging

Debug Logging

OpenPermis uses SLF4J for debug logging. Check out the 3rd party page for the exact version bundled with the OpenPermis.

We decided to use SLF4J since it gives the end user the flexibility to chose the desired logging framework at deployment time.

For more information about SLF4J and its configuration (i.e. the plugins available for other logging frameworks) please check out the two page manual.

Logging vs Auditing

Logging messages issued by the OpenPermis implementation are for debugging and informational purposes only. If you want to add auditing support to your PEP implementation please consult the auditing documentation.

Guidelines

The following guidelines should be adhered to when adding debug log messages in the OpenPermis source code.

Logger Definition

Define a logger for each class in which you would like to add logging as follows:

//---- Static

/**
 * @new
 */
private static final Logger LOGGER =
  LoggerFactory.getLogger(MyImplementation.class);

Make loggers private and static and make sure you use the implementation class of the logger. Resist using foreign logger objects, this only makes debugging harder.

Logging Format

Adhere to the following simple rules when writing debug log messages:

  • Make full english sentences that end with a period.
  • Log all interesting parameters (more helps when hunting down errors).
  • Include exceptions when logging (more is more).
  • Log parameters in the toString() format used by SUN in the JDK.
  • Surround state logged with square brackets to make empty state easily recognizable.

Example:

LOGGER.debug(
  "Processing access decision request for [" + 
  "subject=[{}],resource=[{}],action=[{}],arguments={},timestamp=[{}]].",
  new Object[] { subject, resourceUri, actionName, arguments, timeStamp }
);

Use the SLF4J placeholder {} where possible. If you expand parameters directly this will decrease performance greatly if logging is turned off, see the SLF4J FAQ entry on logging performance.

Exception Logging

Log important exceptions and the cause when you throw them. In a perfect world the exception would be logged at an appropriate location where it is caught, however since this will often be out of our control important exceptions that help tracking down errors should be logged and then thrown.

Example:

final Exception exception = new Exception("Message");
LOGGER.warn("Something happened.", exception);
throw exception;

Note: Only use the above pattern for exception that are not caught by the framework itself, i.e. at customer code boundaries.

Implement toString()

Not exactly a logging topic, but it falls into the same category that's why it is worth mentioning here.

Try to provide a suitable toString() implementation for your objects. The default implementation often lacks the information needed to help debugging, therefore add a toString() implementation as is done by SUN in the JDK for most of the objects.

Example:

//---- Object

/**
 * @new
 */
@Override
public String toString () {
  return new StringBuilder("MyState[").
    append("directory=[").append(getDirectory()).
    append("],files=[").append(getFiles()).
    append("]]").toString();
}

Log Levels

Use the following log levels to simplify debugging:

Level Description
TRACE Not used by OpenPermis.
DEBUG Useful debugging information that is not of general interest. Log messages of this level are usually enabled specifically to track down a problem. Be verbose and include a lot of information.
INFO Logging messages that are of general interest that should always be available when inspecting logs. Be terse and provide important information.
WARN Internal errors that could be recovered and that do not affect the PDP operation. This includes invalid parameters passed to OpenPermis from client code. (Example: Passing null as a parameter to PolicyDecisionPoint.getAccessDecision(...) which is not allowed according to its documentation.)
ERROR Used for unrecoverable internal errors. These are usually accompanied by a shutdown of the PDP.