For uPortal 3.1 a database persistent PortalEvent logger will be included. The logger will use the same JPA/Hibernate persistence API that other new database facing code in uPortal 3 uses. The event driven portal statistics model introduced in uPortal 2.6 is used which allows new events to be logged by this handler by simply adding the appropriate Hibernate mapping information about the class.
Database Event Logging Concerns
When logging portal events to a database serious considerations need to be made about the amount of available space and the performance of the database. A uPortal database is mostly read oriented with only a few writes when a new user logs in or a user changes their layout. The event log database will be primarily writes and can write a significant amount of data.
- As an example a user that is in 5 groups logging in results in 1 new row in STATS_SESSION, 5 new rows in STATS_SESSION_GROUPS, and 2 new rows in STATS_EVENTS.
- Another example of a user viewing their default tab with 6 channels for the first time results in: 13 rows in STATS_EVENTS, 12 rows in STATS_CHANNEL, 12 rows in STATS_FOLDER, and 7 rows in STATS_RENDER_TIME. Note that as with any EventHandler the users and events to be logged can be configured in the statsContext.xml file which can reduce the number of events logged to the database.
Event Logging Configuration
The default uPortal configuration has the database event logger disabled. To enable it two files need to be edited.
- In uportal-impl/src/main/resources/properties/contexts/statsContext.xml uncomment the <ref bean="queueingEventHandler"/> reference in the portalEventMulticaster bean then scroll down and un-comment the entire bottom section in the file. There are specific instructions for doing so in the file.
- In uportal-impl/src/main/resources/properties/contexts/schedulerContext.xml uncomment the <ref bean="statsQueueFlushingTask"/> reference in the timerFactory bean then scroll down and un-comment the statsQueueFlushingTask bean.
To configure which events are logged refer to the JavaDocs for the AbstractLimitedSupportEventHandler. The QueueingEventHandler which sits in front of the persisting bean extends AbstractLimitedSupportEventHandler to event filtering can be configured there.
The QueueingEventHandler is used to batch the persist action for better performance and to reduce database IO. The default configuration is to only store events when there are at least 50 in the queue or every 60 seconds, whichever comes first. This configuration should not need to be changed.
Database Tables
The following tables are used to log portal event information.
Each PortalEvent has a corresponding event type. This is tied to a unique key specified by each implementation of PortalEvent. These keys are logged to STATS_EVENT_TYPE which is referenced by the STATS_EVENT table.
PortalEvents always include an IPerson object representing the portal user that triggered the event. The model this event logger uses is that the first time a PortalEvent is logged for a user a statistics session is created which logs the user id and the groups that user is in to the STATS_SESSION and STATS_SESSION_GROUPS tables. The ID of the stats session is then included with each entry in the STATS_EVENT table.
For each event there will be an entry added to the STATS_EVENT table. Along with possibly entries in STATS_FOLDER, STATS_CHANNEL, and STATS_RENDER_TIME based on what the PortalEvent is for.
PortalEvent Types
| PortalEvent Class | STATS_EVENT_TYPE Key | Affected Tables |
|---|---|---|
| UserLoggedInPortalEvent | LOGIN | STATS_EVENT |
| UserLoggedOutPortalEvent | LOGOUT | STATS_EVENT |
| UserSessionCreatedPortalEvent | SESSION_CREATED | STATS_EVENT |
| UserSessionDestroyedPortalEvent | SESSION_DESTROYED | STATS_EVENT |
| ChannelAddedToLayoutPortalEvent | LAYOUT_CHANNEL_ADDED | STATS_EVENT, STATS_CHANNEL, STATS_FOLDER |
| ChannelUpdatedInLayoutPortalEvent | LAYOUT_CHANNEL_UPDATED | STATS_EVENT, STATS_CHANNEL, STATS_FOLDER |
| ChannelMovedInLayoutPortalEvent | LAYOUT_CHANNEL_MOVED | STATS_EVENT, STATS_CHANNEL, STATS_FOLDER |
| ChannelRemovedFromLayoutPortalEvent | LAYOUT_CHANNEL_REMOVED | STATS_EVENT, STATS_CHANNEL, STATS_FOLDER |
| ChannelInstanciatedInLayoutPortalEvent | CHANNEL_INSTANTIATED | STATS_EVENT, STATS_CHANNEL, STATS_FOLDER |
| ChannelTargetedInLayoutPortalEvent | CHANNEL_TARGETED | STATS_EVENT, STATS_CHANNEL, STATS_FOLDER |
| ChannelRenderedInLayoutPortalEvent | CHANNEL_RENDERED | STATS_EVENT, STATS_CHANNEL, STATS_FOLDER, STATS_RENDER_TIME |
| PortletActionInLayoutPortalEvent | PORTLET_ACTION | STATS_EVENT, STATS_CHANNEL, STATS_FOLDER, STATS_RENDER_TIME |
| PublishedChannelDefinitionPortalEvent | CHANNEL_DEFINITION_PUBLISHED | STATS_EVENT, STATS_CHANNEL |
| ModifiedChannelDefinitionPortalEvent | CHANNEL_DEFINITION_MODIFIED | STATS_EVENT, STATS_CHANNEL |
| RemovedChannelDefinitionPortalEvent | CHANNEL_DEFINITION_REMOVED | STATS_EVENT, STATS_CHANNEL |
| UserAddedFolderToLayoutPortalEvent | LAYOUT_FOLDER_ADDED | STATS_EVENT, STATS_FOLDER |
| UserUpdatedFolderInLayoutPortalEvent | LAYOUT_FOLDER_UPDATED | STATS_EVENT, STATS_FOLDER |
| UserMovedFolderInLayoutPortalEvent | LAYOUT_FOLDER_MOVED | STATS_EVENT, STATS_FOLDER |
| UserRemovedFolderFromLayoutPortalEvent | LAYOUT_FOLDER_REMOVED | STATS_EVENT, STATS_FOLDER |
| PageRenderTimePortalEvent | PAGE_RENDER_TIME | STATS_EVENT, STATS_FOLDER, STATS_RENDER_TIME |
Adding Events / Modifying Mappings
The Hibernate entity mappings for the logged PortalEvents is done in the file uportal-impl/src/main/resources/properties/db/stats/portalEvents.hbm.xml. If you add a new PortalEvent implementation that should be logged to the database it needs to be mapped correctly in this file. Unmapped PortalEvents are ignored by the database logging code.
Reading Events
The Hibernate entity mappings and PortalEvent classes are not designed to be read from the database using Hibernate, only to be a logging facility. Any reporting tools should just use straight SQL as doing large reporting tasks via ORM is not easy and the PortalEvent object model is not designed for such use.