Logging in your OAM plug-in

I've been playing around with the OAM plug-in API and working on putting together a very simple JDeveloper project that includes a custom login form and an OAM plug-in that demonstrates the basics of using the interface.

I'm going to get that blog post out eventually, but for right now I need to talk about logging inside your plug-in.

OAM uses the Java Logger (java.util.logging.Logger and related classes) to record all of the debugging information in an easily manageable way. When you write your first plug-in it can be a bit confusing to figure out how the heck you get your logging messages out. It's not at all complicated, but it does mean you need to understand how OAM manages its logging.

Let's start with the absolutely minimum amount of code you need to log:

package com.oracleateam.iam.oamauthnplugin;

// a bunch of imports go here

public class DemoAuthNPlugin extends AbstractAuthenticationPlugIn {
  public DemoAuthNPlugin() {
    super();
    LOGGER.finest(this.getClass.getName() + " constructor called.");
  }

  // other methods
}

That's it. The bare minimum needed to get logging working.

Of course you need to do a little more work... Click through to see what else you need to do.

But in order to convince the logging layer to actually put that string into a log file we need to actually enable that logging. The OAM docs talk about this in some detail in this section, but here's a quick recap:

Run wlst from the OAM home:

[oracle@linux OAMDomain]$ ~/Oracle/Middleware/Oracle_IAM1/common/bin/wlst.sh

Then connect to the running OAM server and actually enable logging for oracle.oam.plugin (note: the docs talk about a different logger. In OAM 11.1.1.5 I know for a fact that plugins log under oracle.oam.plugin!)

wls:/offline> connect('weblogic', 'ABcd1234', 't3://localhost:7010')
Connecting to t3://localhost:7010 with userid weblogic ...
Successfully connected to Admin Server 'AdminServer' that belongs to domain 'OAMDomain'.

Warning: An insecure protocol was used to connect to the 
server. To ensure on-the-wire security, the SSL port or 
Admin port should be used instead.

wls:/OAMDomain/serverConfig> domainRuntime()
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root. 
For more help, use help(domainRuntime)

wls:/OAMDomain/domainRuntime> setLogLevel(logger="oracle.oam.plugin",level="TRACE:32", persist="0", target="oam_server1")
wls:/OAMDomain/domainRuntime> listLoggers(pattern="oracle.oam.plugin",target="oam_server1")
------------------+-----------------
Logger            | Level           
------------------+-----------------
oracle.oam.plugin | TRACE:32

Do that, upload, distribute, and activate your plug-in and you should be rewarded with something like this appearing in your log file:

[2012-02-01T16:03:38.122-05:00] [oam_server1] [TRACE:32] [] [oracle.oam.plugin] [tid: DistributedCache:DistributionCache:EventDispatcher] [userId: ] [ecid: 0000JKuP1i6DsX55nRx0iZ1FAP
9N000002,0] [SRC_CLASS: oracle.security.am.engines.common.adapters.OAMLoggerImpl] [APP: oam_server] [SRC_METHOD: finest] DemoAuthNPlugin loading

Which log file? servers/oam_server1/logs/oam_server1-diagnostic.log of course!

OK, so that's all well and good, but what if you don't want to log in the same place all the other OAM plug-ins log?

Easy peasy. Just make one change to your code:

package com.oracleateam.iam.oamauthnplugin;

// a bunch of imports go here

public class DemoAuthNPlugin extends AbstractAuthenticationPlugIn {
  private final static Logger LOGGER = Logger.getLogger(DemoAuthNPlugin.class.getCanonicalName());

  public DemoAuthNPlugin() {
    super();
    LOGGER.finest(this.getClass.getName() + " constructor called.");
  }

  // other methods
}

And add a new logger to OAM's configuration:

wls:/OAMDomain/domainRuntime> setLogLevel(logger="com.oracleateam.iam.oamauthnplugin",level="TRACE:32", persist="0",  target="oam_server1",addLogger="1")
wls:/OAMDomain/domainRuntime> listLoggers(pattern="com.oracleateam.iam.oamauthnplugin",target="oam_server1")
-----------------------------------+-----------------
Logger                             | Level           
-----------------------------------+-----------------
com.oracleateam.iam.oamauthnplugin | TRACE:32

And you will be rewarded with lines like this in your log file:

[2012-02-01T16:13:11.713-05:00] [oam_server1] [TRACE:32] [] [com.oracleateam.iam.oamauthnplugin.DemoAuthNPlugin] [tid: DistributedCache:DistributionCache:EventDispatcher] [userId: ]
[ecid: 0000JKuP1i6DsX55nRx0iZ1FAP9N000002,0] [SRC_CLASS: com.oracleateam.iam.oamauthnplugin.DemoAuthNPlugin] [APP: oam_server] [SRC_METHOD: ] DemoAuthNPlugin loading 

The key here is to not go monkeying with the logging.xml file. Just let WLST take care of all of that for you!