Configuring logging for an Assembler Application

The Assembler logs information to the Platform Services Log Server component.

In order to implement this logging feature in an application, you must instantiate a LogServerAdapter and pass it in to the AssemblerFactory, along with any other Event Listeners. To log front-end information, you must also register a ContentItemAugmentAdapter. The LogServerAdapter and ContentItemAugmentAdapter require a RequestEventInitializer and a MdexQueryInfoInitializer to log request event information to the Dgraph request log, so these should also be configured. Registering a MdexQueryInfoInitializer lets you establish the relationship between the Assembler request and its corresponding MDEX Engine queries in the Dgraph request logs. This helps you to identify and troubleshoot problems.

The RequestEventIntiailizer is used to initialize the RequestEvent thread local variable. Similarly, MdexQueryInfoInitializer is used to initialize the MdexQueryInfo thread local variable in the assembly process. If the MdexQueryInfoInitializer is not included in the assembler configuration, then the additional request information will not be included in the Dgraph request log.

In the following example of an assembler-context.xml file in a Spring implementation, note that the RequestEventIntiailizer is configured before the LogServerAdapter and ContentItemAugmentAdapter so that the request event is logged. The MdexQueryInfoInitializer is also configured so that query information such as the request id, and the session id is added to the Dgraph request log. 

                  <bean class="com.endeca.infront.assembler.event.request.RequestEventInitializer">
    <property name="sessionIdProvider" ref="springUtility"/>
    <property name="requestIdProvider" ref="springUtility"/>
</bean>
<bean class="com.endeca.infront.navigation.event.MdexQueryInfoInitializer">
</bean>
<bean class="com.endeca.infront.assembler.event.request.ContentItemAugmentAdapter">
</bean>
<!-- Remove the following lines to disable logging to an Oracle Endeca Log Server -->
<bean class="com.endeca.infront.navigation.event.LogServerAdapter">
    <property name="logServerHost" value="${logserver.host}"/>
    <property name="logServerPort" value="${logserver.port}"/>
    <property name="isSslEnabled" value="${logserver.sslEnabled}"/>
</bean>

The RequestEventInitializer specifies a SessionIdProvider and a RequestIdProvider so you can associate Assembler requests with MDEX query entries in the Dgraph request log. You specify the following properties:

The referenced bean is configured as follows: 

<bean id="springUtility" class="com.endeca.infront.web.spring.SpringUtility" scope="singleton"/>

The ContentItemAugmentAdapter augments content items with front-end application information, such as a user's search and navigation state. As a result, the response content item returned from an assemble() call includes cartridge logging information. 

<bean class="com.endeca.infront.assembler.event.request.ContentItemAugmentAdapter">
</bean>

The LogServerAdapter logs server-side information. You specify the following properties:

In the Spring implementation, it is configured in the assembler-context.xml file as follows: 

<bean class="com.endeca.infront.navigation.event.LogServerAdapter">
    <property name="logServerHost" value="${logserver.host}"/>
    <property name="logServerPort" value="${logserver.port}"/>
    <property name="isSslEnabled" value="${logserver.sslEnabled}"/>
</bean>

The following Dgraph request log shows the request component (reqcom), session ID (sid) , and request ID (rid) information: 

1402522721112 127.0.0.1 - 3 8357 3.13 2.82 200 5684 0 1 /graph?node=0&offset=0&nbins=0&log=reqcom%3dcontentRequestBroker%26sid%3dDD2CAF659BE6CFDFFDED091F69037113%26rid%3d140252272098164091&irversion=640 - Accept%3A+%2A%2F%2A%0D%0APragma%3A+no%2Dcache%0D%0ACache%2DControl%3A+no%2Dcache%0D%0AUser%2DAgent%3A+Java%2F1%2E7%2E0%5F25%0D%0AHost%3A+localhost%3A15000%0D%0AConnection%3A+keep%2Dalive%0D%0A

The request component is the class that made the MDEX Engine query.

All key-value pairs in com.endeca.infront.assembler.event.request.MdexQueryInfo are logged to the Dgraph response log. You can extend MdexQueryInfoInitializer and add the desired key-value pairs. For example: 

public class CustomMdexQueryInfoInitializer extends MdexQueryInfoInitializer {
    public CustomMdexQueryInfoInitializer() {
        super();
    }
    public void assemblyStarting(AssemblerEvent event) {
        super.assemblyStarting(event);
        String customKey = "CUSTOM_KEY";
        String customValue = "CUSTOM_VALUE";
        //Get the MdexQueryInfo associated with the current assembler request
        MdexQueryInfo info = MdexQueryInfoFactory.getMdexQueryInfo();
        //Store the custom information
        info.put(customKey ,customValue);       
    }
}

Depending on the information you wish to include in a session ID object, you can create a custom implementation of the SessionIdProvider interface. For additional information, refer to the Assembler API Reference (Javadoc).

Depending on the information you wish to include in a request ID object, you can create a custom implementation of the RequestIdProvider interface. For additional information, refer to the Assembler API Reference (Javadoc).

The logging implementation in the Discover Electronics reference application uses the Log4J logger. Log level settings are configurable through the properties file located at ToolsAndFrameworks\<version>\reference\discover-electronics-[authoring|live]\WEB_INF\classes\log4j.properties. If you choose to use this implementation in your own application, you can configure the log level by opening the corresponding file.

Locate and uncomment the following line: 

# Uncomment to see Oracle Commerce Assembler debug info.
# log4j.logger.com.endeca.infront.logger=DEBUG

At the DEBUG level, Assembler and cartridge handler entrances and exits are logged, although the details of the navigation context passed in to the cartridge handler do not appear.

You can create custom cartridge handlers to collect and act on any information that is important to your application.

Each invocation of the Assembler creates an associated RequestEvent object that tracks request information.

Information on a RequestEvent is stored as key/value pairs. You can include arbitrary information about an Assembler request by extending the RequestEvent object in a cartridge handler's process method. For example: 

/**
  * Cartridge Handler process method
  */
public void process(ConfigType pContentType) {

	 // Create a new RequestEvent from the global RequestEvent object
	 RequestEvent event = RequestEventFactory.getEvent();

	 // Store arbitrary information
	 event.put("myKey","my arbitrary value");

  ...
}

The NavigationEventWrapper class provides convenience methods for getting and setting common search and navigation information about a request event. It modifies the RequestEvent object specified in the constructor, as in the example below: 

/**
  * Cartridge Handler process method
  */
public void process(ConfigType pContentType) {

	 // Create a new NavigationEventWrapper around the global RequestEvent object
	 NavigationEventWrapper navigationEvent = new NavigationEventWrapper(RequestEventFactory.getEvent());

	 // Store navigation event information
 	navigationEvent.setAutocorrectTo("autocorrected term");

  ...
}

For additional information about the RequestEvent and NavigationEventWrapper classes, including a full list of the convenience methods available for the NavigationEventWrapper, see the Assembler API Reference (Javadoc).

Request event adapter classes perform some action based on information included with a request event.

A request event adapter class implements the handleAssemblerRequest() method in the abstract RequestEventListener class. This method is invoked at the end of the Assembler's assemble() method.

The following is an example of a simple request event adapter: 

/**
 * Add log information to root content item
 */
public class SampleRequestEventAdapter extends RequestEventListener {

    /**
     * Constructor
     * @param sessionIdProvider provides an ID for the current user session
     */
    public SampleRequestEventAdapter() {
        super();
    }

    /**
     * Prints the request event's session id, request id, and search term (if present) to the console
     * @param assemblerRequestEvent the event containing all of the
     * information about the Assembler request
     * @param rootContentItem the Assembler output
     */
    public void handleAssemblerRequestEvent(RequestEvent event, ContentItem rootContentItem) {
        NavigationEventWrapper navigationEvent = new NavigationEventWrapper(assemblerRequestEvent);
        // Print Session ID - Note that the session Id has already been determined and set in the event object
        System.out.println("The current session is: "+event.getSessionId());
        // Print Request ID - Note that the request Id has already been determined and set in the event object
        System.out.println("The request ID is: "+event.getRequestId());
        // Print Search Term
        if (navigationEvent.getSearchTerms() != null && !navigationEvent.getSearchTerms().trim().isEmpty()) {
            System.out.println("The current search terms are: "+navigationEvent.getSearchTerms());
        } else {
            System.out.println("There were no search terms in the current request");
        }
    }
}

The example request event adapter registers an implementation of SessionIdProvider in the constructor. This enables it to retrieve the server session ID.

The Tools and Frameworks installation implements this interface in the included SpringUtility class. You can create your own SessionIdProvider class by extending the SessionIdProvider interface and implementing the getSessionID() method.

The example request event adapter registers an implementation of RequestIdProvider in the constructor. This enables it to retrieve the request ID.

The Tools and Frameworks installation implements this interface in the included SpringUtility class. You can create your own RequestIdProvider class by extending the RquestIdProvider interface and implementing the getRequestID() method.

The Discover Electronics reference application includes the following implementations of the AssemblerEventListener interface:

For additional information about these classes, see the Assembler API Reference (Javadoc).

To use a request event adapter, you must register it with your AssemblerFactory.

You can disable request event adapters by removing them from the AssemblerFactory configuration.

In the reference application, the AssemblerFactory interface is implemented as SpringAssemblerFactory, and the AssemblerEventListener objects are specified as constructor arguments in the Assembler context file: 

<!--
  ########################################################################
  # ASSEMBLER FACTORY
  #
  # Required.
  #
-->
<bean id="assemblerFactory" class="com.endeca.infront.assembler.spring.SpringAssemblerFactory"
      scope="singleton">
    <constructor-arg>
        <bean class="com.endeca.infront.assembler.AssemblerSettings">
            <property name="previewEnabled" value="${preview.enabled}" />
            <property name="previewModuleUrl" value="http://${workbench.host}:${workbench.port}/ifcr" />
        </bean>
    </constructor-arg>
    <constructor-arg>
        <list>
            <bean class="com.endeca.infront.logger.SLF4JAssemblerEventLogger" />
            <bean class="com.endeca.infront.assembler.event.request.RequestEventInitializer">
                    <property name="sessionIdProvider" ref="springUtility"/>
                    <property name="requestIdProvider" ref="springUtility"/>
             </bean>
             <bean class="com.endeca.infront.navigation.event.MdexQueryInfoInitializer">
             </bean>
             <bean class="com.endeca.infront.assembler.event.request.ContentItemAugmentAdapter">
             </bean>
             <!-- Remove the following lines to disable logging to an Oracle Endeca Log Server -->
             <bean class="com.endeca.infront.navigation.event.LogServerAdapter">
                 <property name="logServerHost" value="${logserver.host}"/>
                 <property name="logServerPort" value="${logserver.port}"/>
                 <property name="isSslEnabled" value="${logserver.sslEnabled}"/>
             </bean>
        </list>
    </constructor-arg>
</bean>

The Discover Electronics reference application includes two request event adapters, ContentItemAugmentAdapter and LogServerAdapater.

Adapter

Description

com.endeca.infront.assembler.request.ContentItemAugmentAdapter

Appends request event information to the Content Item returned by the assemble() method. Information is included as a nested Content Item of type AssemblerRequestEvent, with the key endeca:assemblerRequestInformation. For a list of attributes that are available out-of-the-box, see Request Event Attributes.

com.endeca.infront.navigation.event.LogServerAdapter

Formats data from the request event and sends it to the Log Server, which enables Workbench users to generate reports using the Report Generator.

The adapter must be configured with the host and port of the log server. In the reference application, these values are configured in the WEB-INF\assembler.properties file.

The Oracle log server tracks the following click events from the client side of an Assembler application:

Attribute Key

Type

Description

IN_DIM_SEARCH

Boolean

Did the user select a dimension search result.

IN_DYM

Boolean

Did the user select the "did-you-mean" value.

IN_MERCH

Boolean

Did the user select a merch rule (spotlight).

CONVERTED

Boolean

Did an action cause a conversion.

You can include the information collected from these events in your application reports. For more information about the Log Server and Report Generator components, refer to the Platform Services Log Server and Report Generator Guide.

Copyright © Legal Notices