+

Search Tips   |   Advanced Search

Logging custom details of business events for site analysis


Components of the site analysis logging framework for standard (JSR 168 and JSR 268) portlets

    com.ibm.portal.portlet.service.siteanalyzer.PortletSiteAnalyzerLoggingServiceHome

    Service that exposes methods for obtaining a logger instance specialized on the specified request type...

    • ActionRequest
    • EventRequest
    • RenderRequest
    • ResourceRequest

    Portlets obtain this portlet service through a JNDI lookup.

    com.ibm.portal.portlet.service.siteanalyzer.PortletSiteAnalyzerLogger

    Portlets can retrieve an instance of this logger from the PortletSiteAnalyzerLoggingServiceHome. It is valid for the request for which it was created, and it provides methods to query the logger state - enabled or disabled - and to create a site analysis log entry.

    com.ibm.portal.portlet.service.siteanalyzer.ParameterNamesProcessor

    Request parameter names, in particular render parameter names that are encoded into portal URLs, should be as short in length as possible. This recommendation does not leave much space for meaningful parameter names in site analysis log entries. The ParameterNamesProcessor interface allows portlet developers to provide the PortletSiteAnalyzerLogger with a callback for processing request parameter names. Implementations of this interface are called by the site analytics framework before assembling the query string section of the request URI that is written to the site analysis log file.


Activate the portal site analyzer logger for standard portlets

  1. Enable the site analyzer logger for standard portlets using the portal configuration service SiteAnalyzerLogService....

    1. Select the appropriate WAS console, depending on our environment:

      • If the portal runs stand-alone, use the local WAS console.

      • If the portal is installed in a cluster, use the WAS console of the Deployment Manager.

    2. Start the WAS console...

        http://your_server.com:admin_port/ibm/console

      ...and go to...

        Resources | Resource Environment | Resource Environment Providers | Resource environment providers | Scope

      If the portal runs as a single server, select Browse Nodes and select the node.

      If the portal is installed in a cluster, select Browse Clusters and select the portal cluster.

    3. Select WP SiteAnalyzerLogService.

    4. Click Custom Properties.

    5. Do one of the following:

      • Set SiteAnalyzerJSRPortletLogger.isLogging = true.

      • Create a new property named SiteAnalyzerJSRPortletLogger.isLogging and set to true.

        Use java.lang.String as the property type.

    6. When we are done, click Save at the start of the page under Message(s).

    7. Click Save again when prompted to confirm the change.

    8. Optional: If the portal runs in a cluster configuration, replicate the changes to the cluster.

    9. Restart the portal to activate the changes.

  2. Implement a parameter names processor:

    The following code sample shows an implementation of the ParameterNamesProcessor interface. The sample holds a static mapping of possible request parameter names to a more descriptive expression that to be used in site analysis log entries instead. If there is no replacement for a parameter name, the original key is returned to be written to the site analysis log entry as it is. 

    public class ParameterNamesProcessorSample implements ParameterNamesProcessor
{
   private static final Hashtable<String, String> PARAM_NAMES_MAP;
    static    {
      PARAM_NAMES_MAP = new Hashtable();
      PARAM_NAMES_MAP.put("ci", "CurrentItem");
   }
    public String processParameterName(String paramName)
   {
      // get a replacement for the given parameter name or       
      // return the original key if not replacement exists       
      if (PARAM_NAMES_MAP.containsKey(paramName))
      {
         return PARAM_NAMES_MAP.get(paramName);
      }
      else
      {
         return paramName;
      }
   }
}

  3. Retrieve the portlet site analyzer logging service:

    The following code sample shows the init method of a portlet class that looks up an instance of the portlet site analyzer logging service. Additionally, it instantiates a sample implementation of the ParameterNamesProcessor interface. 

    private PortletSiteAnalyzerLoggingServiceHome iSALogServiceHome = null;
 private ParameterNamesProcessorSample iParamNamesProc = null;
 public void init() throws PortletException
{
  com.ibm.portal.portlet.service.PortletServiceHome psh;
  javax.naming.Context ctx = new javax.naming.InitialContext();
   try    
   {
    psh = (PortletServiceHome) ctx.lookup(PortletSiteAnalyzerLoggingServiceHome.JNDI_NAME);
  }    catch (javax.naming.NameNotFoundException e) {
    // error handling   }
    // obtain the service object    
   PortletSiteAnalyzerLoggingServiceHome iSALogServiceHome = (PortletSiteAnalyzerLoggingServiceHome) psh.getPortletService(PortletSiteAnalyzerLoggingServiceHome.class);
   // instantiate the sample parameter names processor   
   paramNamesProc = new ParameterNamesProcessorSample();
}

  4. Retrieve an instance of the portlet site analyzer logger:

    A logger instance depends on a specific portlet request. Its validity is bound to a single request processing cycle. Therefore, the instantiation of the logger must be performed for each request. The service object that is obtained in the previous step makes various methods available to obtain a logger instance. The following code sample shows the retrieval of a logger instance for the current RenderRequest in the doView method of a portlet. The instance of the parameter names processor sample is also passed in to the getLogger method in order to register this callback for the returned logger. Sample: 

    protected void doView(final RenderRequest renderRequest, final RenderResponse renderResponse) throws PortletException, IOException 
{
   final PortletSiteAnalyzerLogger saLogger = iSALogServiceHome.getLogger(renderRequest, renderResponse, iParamNamesProc);
   // further request processing 
}

  5. Logging a business event:

    When a portlet uses the instance of the PortletSiteAnalyzerLogger, the logger writes a business event to the site analysis log file. For example: 

    protected void doView(final RenderRequest renderRequest, 
        final RenderResponse ) throws PortletException, IOException 
{
  // request processing    
  // check whether the logger is enabled   
  if (saLogger.isLogging())
  {
    // create a site analysis log entry     
    saLogger.log("A sample business event");
  }
   // further request processing 
}


Results

Site analysis log for standard portlets: The site analysis log entries written by the PortletSiteAnalyzerLogger have the same structure as log entries created by other types of site analyzer loggers the portal provides. This particular logger also implements the industry standard NCSA Combined.

The following example shows how the URL-encoded representation of the custom business event is written to the request URI section of a log record. Non-ASCII characters are first encoded as sequences of 2 or 3 bytes, using the UTF-8 algorithm, before they are encoded as %HH escapes. The encoded business event precedes the query fragment, which starts with a question mark. Furthermore, the name of the request parameter ciwas replaced by ParameterNamesProcessorSample and now displays in the query fragment of the request URI section of the log record as CurrentItem.

    9.37.3.88 - jdoe [22/Nov/2008:22:11:27 +0100] "GET /Portlet/ 5_8000CB1A00U6B02NVSPH1G20G1/SamplePortlet/A%20sample%20business%20event ?PortletPID=5_8000CB1A00U6B02NVSPH1G20G1&PortletMode=view&PortletState=normal &RequestType=render&CurrentItem=9783000216008 HTTP/1.1" 200 -1 "http://myserver.company.com/Page/6_8000CB1A00UR402F0JC25U1O25/SamplePage" "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.18) Gecko/20081029 Firefox/2.0.0.18" "JSESSIONID=0000JwIm04xm7btVLwzCj9Qo-uj:-1"


Parent Log and analyze server side site data