+

Search Tips   |   Advanced Search

Logging custom details of business events for site analysis


From a business point of view we might want to log custom details of business events.

The procedures described in this topic an its subtopics work only for standard (JSR 168 or JSR 286) portlets.

These are main components of the site analysis logging framework for standard portlets:

To activate and use the portal site analyzer logger for standard portlets...

    li> Activating the site analyzer logger for standard portlets: You enable the site analyzer logger for standard portlets using the portal configuration service SiteAnalyzerLogService. You set its property in the WAS admin console through the resource environment provider WP SiteAnalyzerLogService:

    1. Select the appropriate WAS admin console:

      • If the portal runs standalone, use the local WAS admin console.
      • If the portal is installed in a cluster, use the WAS admin console of the dmgr.

    2. Start the WAS admin console by entering the following URL in the URL location field of a Web browser:

        http://your_server.com:admin_port/ibm/console
      where your_server.com is the name of the server and admin_port is the port assigned to the WAS admin console.

    3. In the navigation click Resources > Resource Environment > Resource Environment Providers.

    4. In the Resource environment providers page, elect the appropriate node or cluster from the scopes pull-down list, or uncheck the Show Scope selection drop-down check box and select one of the following options, depending on the portal environment:

      • 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.

    5. Select WP SiteAnalyzerLogService.

    6. Click Custom Properties.

    7. Do one of the following as required:

      • Select the property SiteAnalyzerJSRPortletLogger.isLogging and change its value to true.

      • Create a new property named SiteAnalyzerJSRPortletLogger.isLogging and set its value to true. Use java.lang.String as the property type.

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

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

    10. If the portal runs in a cluster configuration, replicate the changes to the cluster.

    11. Restart the portal to make the changes become effective.
  1. Implementing 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 to be used in site analysis log entries instead. If there is no replacement for a given parameter name, the original key is returned to be written to the site analysis log entry as it is. Sample: 
    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;
      }
   }
}
  2. 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();
}

  3. 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 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 }
  4. 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. Sample: 
    protected void doView(final RenderRequest renderRequest, 
                      final RenderResponse 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 }

Understand the 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 loggerthat 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 two or three 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 ci has been replaced by ParameterNamesProcessorSample and now appears 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
Related:
Enable site analysis logging
Related reference:
Analysis loggers reference
Understand the site analysis log