Sessionizer annotation usage

First stage

This stage will create hint for sessionizer based on the input raw events.

@Session

This annotation is used to provide hint for sessionizer to create/load session

@Session("SOJMainSession")
select si as _pk_, _ct as _timestamp_, __sessionTTL as _duration_
from PULSAREvent(si is not null and _ct is not null);

The statement should return pk as the identifier of the session. And it can also return optional timestamp as the event timestamp, duration as the session max inactivity time.

Second stage

These annotations used in the main sessionizer and sub sessionizer to run sessionizer logic.

@SubSession

This annotation is used to provide hint for sessionizer to create/load sub session, only can be used in the main sessionizer.

@SubSession("AppSession")
select app as _pk_
from PULSAREvent(p is not null);

The statement should return pk as the identifier of the sub session. And it can also return an optional duration as the sub session max inactivity time.

@UpdateState

Save sate to session, it will use the selected field (key-value map) to store it into session variable.

@UpdateState
select p as page from PULSAREvent;

Store the value of p tag into session variable page. The state can be accessed via session.string('page') if the p type is string. session.int('page') if p type is int. It can select one or more fields in the select clauses. The p as page is optional and you can use p directly if you want to use p as the name.

@UpdateCounter

Create/Increase session counter

@UpdateCounter("HomePageView")
select * from PULSAREvent(pageGroup = 'HomePage');

Increase the session counter HomePageView if the pageGroup is HomePage. The counter can be accessed from session.int('HomePageView') to read the counter.

@AppendState

Append data into a list variable

@AppendState(name="pageList ", colname="page", unique=”true”)
select p as page from PULSAREvent;

Append the current page to session pageList variable, the AppendState has a optional maxLength to control whether the list is bounded or not, the unique indicate whether it include duplicated values. You can use session.list('pageList') to read the data.

@UpdateMetadata

Save to session metadata, metadata will be stored as static info of the session, and it will be added to the session marker event automatically. Most case is extract a few fields like IP, UserAgent from first event to store it in session.

@UpdateMetadata
select ipv4 as ip
from PULSAREvent (session.eventCount = 1);

Store the ipv4 value into the metadata. And metadata can be accessed from metadata.string('ip') if the ipv4 type is string.

@UpdateDuration

Change session max idle time.

@UpdateDuration
select 60000 as _duration_
from PULSAREvent (session.botEventCount = 1);

Change session duration to 1 minute if it is a bot session.

@DecorateEvent

Decorate new event info into the current event.

@DecorateEvent                    
select metadata.string('Referrer') as _Referrer 
from PULSAREvent(metadata.string('Referrer') is not null);

Decorate first event referrer to all following events. The DecorateEvent can be used on both raw event and sessin marker event. If use it on session marker event, the marker event should be declared on the EventDefition xml.

Debugging sessionizer

@Debug

Debug is the built-in Esper annotation, it will print verbose message when it execute the EPL statement.

@DebugSession

This is used to count the statement when it be executed, the above @Debug is quite heavy as it print huge logs.

// Will count the raw event which Referrer is not null and show it on monitoring page
@DebugSession(counter="NotNullReferrerCounter")                  
select * 
from PULSAREvent(Referrer is not null);

// Will count the raw event group by Referrer and show it on monitoring page
// Will be shown like Referrer-abc : 1234, Referrer-xyz: 3456
@DebugSession(counter="NotNullReferrerCounter", colname="Referrer ")                  
select Referrer  
from PULSAREvent(Referrer is not null);

The counter can be accessed from http://host:port/EsperSessionizerCounter?$format=xml the @DebugSession have an optional audit attribute which do same thing as @Debug, print logs on the log file.

Accessing Session state and metadata

The session state include metadata and states. it can be accessed via metadata and session variables on EPL. The metadata and states should be primitive types or list of primitive types, for complex type, better to encode/decode it as json string.

The metadata is a map, and it can only be updated by above @UpdateMetadata, and it can be accessed in the EPL via metadata variable, to avoid cast the value, the metadata has multiple get methods to access the value by the type. metadata.string('xyz') will return string, metadata.boolean('abc') will return boolean. the para meter are the name of the keys. See API for detail.

Access the session is similar with the metadata, session is a map and have some additional attributes, See API for detail.

For subsessionizer, it has two additional parentSession and parentMetadata variables to access its parent session data.

The session and metadata can be both used on where filter and also select clause.

Output session metadata and states

On raw event, it can use @DecorateEvent to add the metadata and states on the raw event.

For example:

@DecorateEvent                    
select metadata.string('Referrer') as _Referrer 
from PULSAREvent(metadata.string('Referrer') is not null);

@DecorateEvent                    
select session.string('page') as _prevPage
from PULSAREvent(session.string('page') is not null);

On marker event, by default, it will add all metadata into the session marker event. If it want to decorate more info, it need first make sure the marker event in the EventDefinition and then use @DecorateEvent.