Monday, August 29, 2016

Web Service Logging

I wrote some content for my employer about logging Web Service requests and replies. The blog entry can be found at Interloc Solutions' Blog.

Web services have made a lot of things easier, and a lot of things better. They make it possible to integrate other applications with IBM Maximo without the hassle of providing, and keeping up to date, a jar file of business objects to use with RMI. Maximo also makes creating web services very easy. From the Integration -> Web Services Library application, it is possible to create web services from an Object Structure, an Enterprise Service, or from a Service Class.

The decoupled nature of web services adds its own set of problems, notably how to trace problems between the two systems. At some point, it is necessary to see what message was received by Maximo and what was sent back by Maximo. There are two common approaches: 1) enable axis debugging or 2) use a proxy.

Under the hood, Maximo uses axis to implement web services. Axis has options for logging messages which get captured in SystemOut. It makes SystemOut very large and it is difficult to find a transaction and its reply. Using it usually involves turning it on for a short test, then turning it back off as soon as possible. It is not useful for diagnosing a problem after the fact.

Configuring a proxy makes it easy to see a request and a response pair, and it doesn’t fill up the Maximo logs. Unfortunately, it requires configuring the client to use the proxy instead of communicating directly to Maximo. This might be acceptable in a development environment, but it’s not feasible in a production environment. If SSL/TLS is used or required, additional complexity is added to using a Proxy. This option isn’t useful for diagnosing problems after the fact either.

A third option is to use a custom Implementation class that logs the request and reply. In essence, the implementation class looks like this:

public class LoggingMOSWebService extends MOSWebService {
    /* ... snip ... */

    public OMElement processDocument(OMElement arg0) throws RemoteException {
        log("request", arg0);
        OMElement rc = super.processDocument(arg0);
        log("reply", rc);
        return rc;
    /* ... snip ... */

This class is compiled and included in the Maximo meaweb application. Maximo has to be rebuilt, redeployed, and restarted for the class to become available.

To use the class, specify it as the Implementation class when creating the web service, like this:

Now, whenever a web service call is made to MXASSET, the request is logged in a file, and the reply is logged in a separate file. The filenames will indicate the web service that was called and associate the request and replies together. This can be deployed in a production environment without negative performance impact, and without filling the Maximo logs. It is important to schedule a job to clean up the files periodically. The data is available in a post mortem situation to help diagnose problems.

A complete set of logging classes has been created and is available on GitHub here:

To use it,
  1. Build the jar file by running: ant package.
  2. A file called wslogging-1.0.0.jar will be created in distrib/jars. Copy this file into maximo/meaweb/webmodule/WEB-INF/lib
  3. Rebuild and redeploy the maximo.ear file.
  4. Create a maximo property called interloc.mea.log for the directory where log files will be created.
  5. For those web services you want to log, create using, or update with, the following classes:
Service Type Implementation Class
Object Structure Service
Standard Service
Enterprise Service

The log files will have the following naming convention: servicename_uuid_[request|reply]_timestamp.uniqifier.xml
For example, MX_ASSET_urn_uuid_6E17F23EA79C2646741470776643777_request_20160809_170421.062823027.xml represents the request on the MX_ASSET web service, with uuid 6E17F23EA79C2646741470776643777, made on August 9, 2016 at 5:05:24 PM.

The reply to this request was in: MX_ASSET_urn_uuid_6E17F23EA79C2646741470776643777_reply_20160809_170442.088323028.xml

I use this at my current client. We don’t need to refer to the transactions often, but when we do, they are nice to have.