XML Schema Documentation for http://beet.sourceforge.net/schema/bt/1.1

Import this schema into your Spring beans definition file (namespace http://www.springframework.org/schema/beans) to configure behavior tracking.

<bt:config>

Container for behavior tracking elements in a Spring configuration file. <bt:config> is "syntactic sugar" within a Spring bean configuration file and is entirely optional; you can include any of its allowed child elements directly in the file instead.

Typically a <bt:config> element will contain one or more <bt:manager> elements. Most applications will only need one <bt:manager> definition. Other elements like <bt:xml-persister> and <bt:session-context> will usually appear as children of a <bt:manager> element. It is useful to include them directly under <bt:config> when you want to make them public for injection into application beans that are not part of the behavior tracking framework, or if you have multiple <bt:manager> tags that share a persister, and so on.

<bt:manager>

Java Bean Type:com.mtgi.analytics.BehaviorTrackingManager

This is the fundamental element required to enable behavior tracking in an application: method call tracking, HTTP request tracking, and JDBC tracking all require this element to appear in Spring configuration.

If no "id" attribute is specified, the implicit name "defaultTrackingManager" is assumed. If there is more than one <bt:manager> defined, you must define a unique "id" value for each.

<bt:manager> Attributes
AttributeUseDescription
application required

Arbitrary text string recorded as the "application" attribute of each logged event.

flush-thresholdoptional

Maximum number of events recorded before data is automatically flushed to the persister. Default is 100 if unspecified.

task-executoroptional

Bean name of a task executor for performing event logging operations. If unspecified, a private thread pool is maintained for this purpose. The default behavior is strongly recommended, as unbounded memory growth is possible if events cannot be logged in a timely fashion as they are recorded.

track-method-expressionoptional

An AspectJ AOP pointcut expression identifying methods that should generate behavior tracking events. This is a simplified alternative to using <bt:advice> in combination with standard Spring AOP configuration.

flush-scheduleoptional

Quartz Cron expression describing how often events should be flushed to the persister. Default is every 5 minutes if unspecified.

register-mbeansoptional

Boolean expression indicating whether JMX mbeans for this manager should be registered with the platform MBean Server. Defaults to false if unspecified.

mbean-serveroptional

When register-mbeans="true", specify a reference to the MBeanServer instance on which mbeans should be registered. Defaults to the platform MBeanServer if unspecified.

scheduleroptional

Bean name of a Quartz scheduler bean to use for timed flush operations. If unspecified, a private instance will be created. The default behavior is strongly recommended.

persisteroptional

Bean name of a BehaviorEventPersister implementation defined in the applicaton context. Use in place of a nested persister element (e.g. <bt:xml-persister>, <bt:jdbc-persister>).

session-contextoptional

Bean name of a SessionContext implementation defined in the applicaton context. Use in place of a nested <bt:session-context> element.

<bt:manager> Nested Elements

<bt:persister-chain>

Configure a multiple persisters for this manager.

<bt:xml-persister>

Configure XML logging for this manager. This is the default logging type if none is specified, so this is only necessary if you want to change any of the defaults, e.g. specify log file location or change the log rotation schedule.

<bt:jdbc-persister>

Configure JDBC logging for this manager.

<bt:mbean-persister>

Configure JMX monitoring for this manager. Event statistics are aggregated in MBeans, where they can be viewed from a JMX console for monitoring quality-of-service.

<bt:custom-persister>

Configure a custom BehaviorEventPersister implementation for this manager.

<bt:session-context>

Specify the bean name of a SessionContext implementation to use with this BehaviorTrackingManager. An alternative to a nested <bt:session-context> element.

<bt:http-requests>

Activate logging of http requests using this manager. All parameters are logged unless the "parameters" attribute is specified. Similarly, all requests are logged, unless one or more "uri-patterns" are specified.

Use of this element requires a servlet container supporting JSP 2.0 and higher, and requires beet.jar to be placed in WEB-INF/lib, not in a shared libraries folder or in an EAR library folder. If you can't use bt:http-requests for these reasons, you must use the BehaviorTrackingFilter servlet filter class instead.

Adding BehaviorTrackingFilter to web.xml achieves almost exactly the same behavior as adding <bt:http-requests> to your Spring configuration. Both methods record HTTP request information and parameter values, but only the Filter can log response information such as HTTP return code and error information. <bt:http-requests> is thus simpler to use, while BehaviorTrackingFilter is slightly (very slightly) more powerful.

<bt:http-requests>

Activate logging of http requests using this manager. All parameters are logged unless the "parameters" attribute is specified. Similarly, all requests are logged, unless one or more "uri-patterns" are specified.

Use of this element requires a servlet container supporting JSP 2.0 and higher, and requires beet.jar to be placed in WEB-INF/lib, not in a shared libraries folder or in an EAR library folder. If you can't use bt:http-requests for these reasons, you must use the BehaviorTrackingFilter servlet filter class instead.

Adding BehaviorTrackingFilter to web.xml achieves almost exactly the same behavior as adding <bt:http-requests> to your Spring configuration. Both methods record HTTP request information and parameter values, but only the Filter can log response information such as HTTP return code and error information. <bt:http-requests> is thus simpler to use, while BehaviorTrackingFilter is slightly (very slightly) more powerful.

<bt:http-requests> Attributes
AttributeUseDescription
parametersoptional

If specified, a comma-separated list of request parameters that should be logged with behavior events. If unspecified, all parameters are logged.

name-parametersoptional

If specified, a comma-separated list of request parameters that should be included as part of the event name. This is useful if you want to differentiate events by key parameter values, rather than by URL alone. If unspecified, no parameters are included in the event name.

uri-patternoptional

Equivalent to a single nested uri-pattern element, provided as an attribute for syntactic convenience.

event-typeoptional

The value to log for event type when recording http requests. Defaults to "http-request" if unspecified.

<bt:http-requests> Nested Elements

<bt:uri-pattern>

A regular expression identifying URIs that should be logged to the behavior event persister. The value of HttpServletRequest.getServletURI() will be matched against this expression.

This element has equivalent behavior to the uri-pattern attribute, but can appear multiple times.

<bt:uri-pattern>

A regular expression identifying URIs that should be logged to the behavior event persister. The value of HttpServletRequest.getServletURI() will be matched against this expression.

This element has equivalent behavior to the uri-pattern attribute, but can appear multiple times.

<bt:advice>

Java Bean Type:com.mtgi.analytics.aop.BehaviorTrackingAdvice

Defines an AOP advisor that logs a behavior tracking event for each advised method call. Generally you can use the track-method-expression attribute of <bt:manager> to achieve the same result; <bt:advice> tags are not strictly necessary. <bt:advice> is provided for fine-grained integration of behavior tracking with other AOP advice. For example, you can control whether behavior tracking events occur inside or outside of transaction boundaries.

<bt:advice> Attributes
AttributeUseDescription
tracking-manageroptional Java Bean Type: com.mtgi.analytics.BehaviorTrackingManager

The bean name of the BehaviorTrackingManager instance that is to be used to register events.

This attribute is usually optional, only required if there is more than one <bt:manager> defined by the application.

<bt:persister-chain>

Java Bean Type:com.mtgi.analytics.ChainingEventPersisterImpl

A delegating BehaviorEventPersister that sends events to a list of persisters. For example, you can configure both an mbean-persister for JMX statistics monitoring and an xml-persister to store raw data. Normally this element will occur as a child of <bt:manager>.

<bt:persister-chain> Nested Elements

<bt:xml-persister>

Add an XML logging persister to the chain.

<bt:jdbc-persister>

Add a JDBC logging persister to the chain.

<bt:mbean-persister>

Add a JMX monitoring persister to the chain.

<bt:custom-persister>

Add a custom BehaviorEventPersister implementation to the chain.

beans:ref

Add a reference by name to a persister bean defined elsewhere in the Spring configuration.

beans:idref

Add a reference by ID to a persister bean defined elsewhere in the Spring configuration.

<bt:xml-persister>

Java Bean Type:com.mtgi.analytics.XmlBehaviorEventPersisterImpl

Defines behavior tracking event persistence to a rotating XML log file. Support is provided for binary XML and GZIP compression. Generally this element will appear as a child of <bt:manager> without an "id", though it is possible to declare it as a top-level bean if you want to inject it into other application beans.

<bt:xml-persister> Attributes
AttributeUseDescription
fileoptional

Path to XML log file. Defaults to behavior-tracking.xml in the process working directory.

rotate-scheduleoptional

Quartz Cron expression for the log file rotation schedule. Defaults to daily at midnight if unspecified.

binaryoptional

Enable binary (FastInfoset) XML logging. Defaults to true.

compressoptional

Enable GZIP logfile compression. Defaults to true.

<bt:jdbc-persister>

Java Bean Type:com.mtgi.analytics.JdbcBehaviorEventPersisterImpl

Defines behavior tracking event persistence to a JDBC DataSource. Optional support is provided for JDBC batch fetching. Generally this element will appear as a child of <bt:manager> without an "id", though it is possible to declare it as a top-level bean if you want to inject it into other application beans.

<bt:jdbc-persister> Attributes
AttributeUseDescription
batch-sizeoptional

Statement batch size for persistence operations, only used if underlying JDBC driver supports batching. Default is 25.

<bt:jdbc-persister> Nested Elements

<bt:data-source>

Specifies the data source to which events are persisted.

<bt:id-sql>

Overrides the default SQL statement used to retrieve new event IDs.

<bt:data-source>

Specifies the data source to which events are persisted.

<bt:data-source> Attributes
AttributeUseDescription
refoptional

<bt:data-source> Nested Elements

beans:ref

beans:idref

<bt:id-sql>

Overrides the default SQL statement used to retrieve new event IDs.

<bt:id-sql> Attributes
AttributeUseDescription
incrementoptional

Increment between consecutive values returned by the ID SQL statement. If greater than 1, it is assumed that the application can interpolate ID values in between calls. For example, if increment=25 and the ID SQL returns 15, the application will use all integers from 15 to 39 as unique IDs before executing the ID SQL again.

<bt:mbean-persister>

Java Bean Type:com.mtgi.analytics.jmx.StatisticsMBeanEventPersisterImpl

Stores aggregate event statistics in memory, for access from a JMX console. Generally this element will appear as a child of <bt:manager> without an "id", though it is possible to declare it as a top-level bean if you want to inject it into other application beans.

<bt:mbean-persister> Attributes
AttributeUseDescription
serveroptional

Specify a reference to the MBeanServer instance on which mbeans should be registered. Defaults to the MBeanServer used by any enclosing <bt:manager> tag, or the platform MBeanServer if not enclosed in a <bt:manager> tag.

<bt:custom-persister>

Java Bean Type:com.mtgi.analytics.BehaviorEventPersister

Defines a custom com.mtgi.analytics.BehaviorEventPersister implementation. Generally this element will appear as a child of <bt:manager> without an "id", though it is possible to declare it as a top-level bean if you want to inject it into other application beans.

<bt:session-context>

Java Bean Type:com.mtgi.analytics.SessionContext

Specifies a custom SessionContext implementation, which provides the user ID and session ID for logged events. If no session-context is specified, then com.mtgi.analytics.servlet.SpringSessionContext is used if we are determined to be in a Spring web application; otherwise com.mtgi.analytics.JAASSessionContext is used.

This element has the syntax of a standard Spring bean definition; e.g. specify "id" and "class" attributes, as well as nested <property> elements.

Attribute bt:tracking-manager

Java Bean Type:com.mtgi.analytics.sql.BehaviorTrackingDataSource

Annotates a Spring bean definition for behavior tracking. The value of this attribute should be the ID of the <bt:manager> instance to use, or simply "defaultTrackingManager". Currently this attribute is only supported for DataSource bean definitions.