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:
- 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).
- 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.
- 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 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:
- In the session parser (instance.PARSER.something), "this" will be the Session object.
- A new event is created so that you can use Event.add2EI and Event.setDeviceEventTime and so forth.
- In the parsing routines, sessRecs (or the variable you declare) is the array of records returned by retrieve() from the session.
- The first record in that set is the record that should be used to contain all of your partial results.
- The records from index 1 thru sessRecs.length-1, therefore, represent the records you stored in the session.
- You must pass your newly created Event to the Session.send() method for proper operation.
Defined in: session.js.
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 Attributes | Field Name and Description |
---|---|
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 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.
|
|
clear()
Empties out a session and sets it to null.
|
|
<static> |
Session.get(key)
Returns a session, if any exists, associated with a given key.
|
getKey()
Session.getKey() returns the key for this session.
|
|
Parser()
The parser used to process the Session once it expires.
|
|
retrieve()
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.
|
|
toString()
Describes a session as a string.
|
- Parameters:
- {String} key
- - The key used to uniquely identify this session
- {Number} maxRecs
- - maximum number of records to be stored in this 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
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
- Parameters:
- {Number} expiry
- # of seconds before this session expires
- Returns:
- {Boolean} Result
- Returns:
- {Boolean} Result
- Parameters:
- {String} key
- The key used to refer to the Session
- Returns:
- {Session} The Session associated with the key
- Returns:
- {String} The Session key
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
- Parameters:
- {Object} event
- The event which will be sent to Sentinel.
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
- Returns:
- {String} Description of session