Class Index | File Index

Classes


Class Session

The Session object is used for temporary record storage when an event source does not provide complete information in a single record. The basic concept is that a storage area is created where multiple "sessions" can be stored - each session is made up of one or more records, and has a key that is used to access that session. Each session uses a key, which should uniquely identify the session and allow new events to be matched against and added to that session. Often related events will have a grouping ID or similar concept, and you might want to combine that with an IP address or other source identifier to prevent overlaps.

In most cases, you will gather up a set of records, storing each one in the associated session, until a given session has enough information to generate a full event. It is possible to explicitly fetch a session and process it, if for example you are using it to store referential data you will add to multiple events, but more typically you will have something indirectly trigger the processing of a session. There are three triggers:

  1. Record count: you can set a threshold for the number of records that should be stored in the session (this is set per-session, so you can base it on the type of session) being stored).
  2. Wallclock timer: The session can be set to persist for a set number of wall-clock seconds, and then be processed. A method is used to attach a wallTimer.
  3. Event timer: The session can be set to persist for a set number of pseudo-seconds, which are calculated based on the perceived time according to the received events, and then be processed. A method is used to attach an eventTimer.
Note that for the Event timer, each event source might have its own idea of time, so you should definitely ensure that when this is used the session key includes an event source ID like an IP address. Also, "time" will not advance unless a new event record with a later time is received from that source, so there are cases where sessions will never process if data stops flowing. You may want to include a longer Wallclock timer to protect against this case.

Note that the default Collector template automatically creates an empty storage area called instance.STORE - the normal Session methods will store sessions in this area. The key must be specified but all other arguments are optional.

Finally, in order to parse a Session the preferred method is to let it expire or overflow (as above), the template will then call a pre-define parsing method on the Session that you've attached via the addParser() method (in other words, the Session will parse itself). Within the Session, your parsing code should use the retrieve() method to fetch the array of stored records, but note that record number 0 is special: it's empty by default, and all your partial results should be stored there. When you send() the Session, record 0 will be used as the source for mapping data into the output event. Example:

// in instance.initialize():
instance.PARSER.audit = function() {
		var newEvt = new Event(instance.CONFIG.protoEvt);
		var sessRecs = this.retrieve();
		
		switch (sessRecs[sessRecs.length-1].hdrMap.type)
		{
			case "SYSCALL":
				sessRecs[0].parsesyscall(sessRecs,newEvt);
				this.send(newEvt);
				break;
			case "CONFIG_CHANGE":
       sessRecs[0].parseconfig(sessRecs,newEvt);
				break;
			default:
				sessRecs[0].sendUnsupported();
				return false;
				break;
		}
	}
// in Record.prototype.parse():
 this.evtgrpid = this.s_RXBufferString.substr(10,25);
 var sessionKey = this.s_RV24 + ":" + this.evtgrpid;
	var sess = Session.get(sessionKey.trim());
	if ( !sess ) {
		sess = new Session(sessionKey);
		sess.addWallTimer(instance.CONFIG.params.Session_Timeout);
		sess.addParser(instance.PARSER.audit);
	}
	sess.store(this);

Note that:


Defined in: session.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Session(key, maxRecs)
Constructs a new event Session to be used to store partial Records which will later be combined into an Event.
Field Summary
Field Attributes Field Name and Description
 
Key
The key used to reference the Session.
 
The maximum number of records this Session can hold.
 
An array to hold the records stored in the Session.
Method Summary
Method Attributes Method Name and Description
 
addEvtTimer(currentTime, expiry, timeParser)
Adds an event-based timer to the session.
 
addParser(parser)
Adds a parser that will be automatically called when the session expires.
 
addWallTimer(expiry)
Adds a wallclock-based timer to this session.
 
Empties out a session and sets it to null.
<static>  
Session.get(key)
Returns a session, if any exists, associated with a given key.
 
Session.getKey() returns the key for this session.
 
The parser used to process the Session once it expires.
 
Returns an array of the stored records in this session.
 
send(event)
Sends this Session as an event to Sentinel.
 
store(rec)
Adds a partial record as part of the session.
 
Describes a session as a string.
Class Detail
Session(key, maxRecs)
Constructs a new event Session to be used to store partial Records which will later be combined into an Event.
Parameters:
{String} key
- The key used to uniquely identify this session
{Number} maxRecs
- maximum number of records to be stored in this session
Field Detail
{String} Key
The key used to reference the Session.

{Number} MaxRecs
The maximum number of records this Session can hold. Set this to automatically trigger processing when this number of records is reached.

{[Record]} Records
An array to hold the records stored in the Session. NOTE: The first Record is actually a blank record which will be used to hold your parsing results when you parse the Session. Records you add to the session will start at index 1.
Method Detail
{Boolean} addEvtTimer(currentTime, expiry, timeParser)
Adds an event-based timer to the session.

For now, implemented as a wall timer. This is experimental and will change.

Parameters:
{Number} currentTime
The current time according to the event source
{Number} expiry
Number of seconds for this session to persist (according to event-based time starting with the first event in the session)
timeParser
Returns:
{Boolean} Result

{Boolean} addParser(parser)
Adds a parser that will be automatically called when the session expires. The parser should be defined as a function that can be attached to the session. instance.PARSER is provided as a convenient place to store pre-defined parser routines.

Example:

// ...in initialize() method
instance.PARSER.login = function() {
  rec.username = recs[0].s_RXBufferString.substr(12,36);
  ...
}
// ..in parse() method after a new session has been created
sess.addParser(instance.PARSER.login);
Parameters:
{Function} parser
- The parser function to attach to this session
Returns:
{Boolean} Result

{Boolean} addWallTimer(expiry)
Adds a wallclock-based timer to this session. Pass in the number of seconds to wait before the session expires; this will be added to the current time to set a expiration time for this session.
Parameters:
{Number} expiry
# of seconds before this session expires
Returns:
{Boolean} Result

{Boolean} clear()
Empties out a session and sets it to null.
Returns:
{Boolean} Result

<static> {Session} Session.get(key)
Returns a session, if any exists, associated with a given key.
Parameters:
{String} key
The key used to refer to the Session
Returns:
{Session} The Session associated with the key

{String} getKey()
Session.getKey() returns the key for this session.
Returns:
{String} The Session key

Parser()
The parser used to process the Session once it expires.

{Record[]} retrieve()
Returns an array of the stored records in this session. Usually this is done by the parsing routines attached to sessions. NOTE: The first Record is actually a blank record which will be used to hold your parsing results when you parse the Session. Records you add to the session will start at index 1.

Example:

instance.PARSER.parseSession = function() {
  partialRecs = sess.retrieve();
  // parse data from partialRecs into partialRecs[0]
  var sessEvt = new Event(instance.protoEvt);
  this.send(sessEvt);
  return true;
}
Returns:
{Record[]} Records in the Session

send(event)
Sends this Session as an event to Sentinel. Note that before you send a Session, you must (in the parsing method attached to the session): 1) Create a new, empty event 2) Parse the data in stored records (indices 1 thru n), storing results into the record at index 0. 3) Set the deviceEventTime, taxonomy key, and any extended information on the new event 4) Call this method, passing in the new event.
Parameters:
{Object} event
The event which will be sent to Sentinel.

{Boolean} store(rec)
Adds a partial record as part of the session.

Example:

// in Record.parse() routine...
if ( this.partial ) {
  sess.store(this);
  return false;
}
Parameters:
{Record} rec
The Record object to store in the session.
Returns:
{Boolean} Result

{String} toString()
Describes a session as a string.
Returns:
{String} Description of session

©2011
Documentation generated by JsDoc Toolkit 2.0.2 on Mon Mar 12 2012 12:04:08 GMT-0400 (EDT)