clickstream - Clickstream Overview
Utility to track the current users on your site, and where they've been in detail. This allows you to track 'click streams' or 'traffic paths' across your site. Please visit the JIRA change log to see the latest developments in Clickstream.
Features
- Start tracking click stream when users' sessions begin (via a Listener).
- Track information with each click the user makes (via a Servlet Filter).
- Log the complete click stream to a file or PrintStream when the users' session ends.
- Try to discover whether the user is a bot, and filter appropriately (currently 252 bots are detected).
- JSP and/or Servlet front-ends to browse the currently active click streams.
Installation
Put clickstream-@VERSION@.jar and commons-logging.jar in [web-app]/WEB-INF/lib and then add the following to [web-app]/WEB-INF/web.xml within the <web-app> tag:
<filter>
<filter-name>clickstream</filter-name>
<filter-class>com.opensymphony.clickstream.ClickstreamFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>clickstream</filter-name>
<url-pattern>*.jsp</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>clickstream</filter-name>
<url-pattern>*.html</url-pattern>
</filter-mapping>
<listener>
<listener-class>com.opensymphony.clickstream.ClickstreamListener</listener-class>
</listener>
This tracks any request for a JSP or HTML file. Whenever an HttpSession is invalidated, the complete click stream for that session will be logged. If you want to track other clicks (eg. TXT or PDF files), just add more filter mappings.
A full web.xml example is available here.
Front-ends
- JSP: you can drop in the JSP files clickstreams.jsp and viewstream.jsp to display the current Clickstreams active in the application.
- Servlet: you can configure your web.xml to include the ActiveStreamsServlet to display the current Clickstreams active in the application.
Configuration
Logging is quite basic (you can however integrate with Log4J). If you need more advanced logging, implement the com.opensymphony.clickstream.logger.ClickstreamLogger interface and provide any sort of persistence method you desire.
By default Clickstream is configured to use the com.opensymphony.clickstream.logger.SimpleClickstreamLogger class to handle logging. This logger does nothing more than send an INFO log statement to the Jakarta Commons Logging utility, which in turn can talk to several logging providers, including Log4j.
You can change this behavior by creating a clickstream.xml config file and placing it in your application's classpath, usually [web-app]/WEB-INF/classes. The config file should be in the following form:
<clickstream>
<!-- there can only be one logger -->
<logger class="com.opensymphony.clickstream.logger.SimpleClickstreamLogger"/>
<!-- there can be zero or more bot-hosts -->
<bot-host name="someBotHost"/>
<!-- there can be zero or more bot-agents -->
<bot-agent name="someBotAgent"/>
</clickstream>
If you wish to provide your own logger, visit the Clickstream JavaDoc.
Container Specific Issues
BEA WebLogic 8.1 (SP2) throws NullPointerException (when setting the attribute NULL for the clickstreams in the ServletContext on contextDestroyed) when the Clickstream application is stopped from the console. Apply patch CR133558 (included in SP3).
External Documentation
- Track Your Users With EAServer - A Sybase White Paper by Berndt Hamboeck.
- Filter code with Servlet 2.3 model, paragraph "Who's on your site, and what are they doing?" - by Jason Hunter.
The modifications to Clickstream mentioned in these documents are already integrated, don't apply them.