Grouping Related Events Into Sessions
Group events that are contextually related into sessions where you can observe event sequences and the outcomes of those event sequences. Gain insight into user activity and network activity by observing the sequence of events that occur in a session.
You can use events to tell you what a user did at a specific time, but you can use transactional sessions to tell you what the user did before and after an event. Transactions give you full detail such as a purchase on the Internet, or an unauthorized login attempt.
The session ID is unique and is assigned to events in the same session. You define the session based on parameters such as time, user name, login, or any other criteria. You use the SESSION BY clause to create the unique sessions.
For example, use the transactional sessions to do these tasks:
Define a user activity based on web-access events that includes a unique combination of activities.
Group events by a specific user behavior session such as website visits, downloads, or emails sent.
Record when users login to and logout of your network, and how long they log in for. The logout closes the related transaction that is initiated by the login.
Pick an activity that you want to track and define the criteria for the session activity.
To create sessions, use the SESSION BY clause by using the following format.
SESSION BY <TimeExpression> <AQL_expression_list> BEGIN <booleanExpression> END <booleanExpression>
The following table describes the session parameters.
Table 1: Session parameters
Description
Time <TimeExpression>
Time
<AQL_expression_list>
AQL expression list
BEGIN <booleanExpression>
Starts a new session
END <booleanExpression>
The END clause is optional, and is used to finish the session.
The SessionId changes when any AQL expression value changes or when the BEGIN or END booleanExpression is TRUE.
To test an example, take the following steps:
To go to the JSA API documentation page, from the Help menu, click Interactive API for Developers.
Click 8.0 or the highest version to expand the menu.
Click /ariel >/searches.
Click the Post tab.
Enter your AQL query in the Value field for the query_expression parameter.
For example,
Select sessionID, DATEFORMAT(starttime, 'YYYY-MM-dd HH:mm:ss') start_time, username, sourceip, category from events into <your_Cursor_Name> where username is not null SESSION BY starttime username, sourceip BEGIN category=16001 start '2016-09-14 14:20' stop '2016-09-14 14:50'
The <your_cursor_name> is any name that you want to use for the results output.
Click Try it out.
If the query runs without errors, the response code is 201.
Click /ariel >/ searches > >/{search_id} >/results
The 8.0 - GET - /ariel/searches/{search_id}/results page opens.
In the Value field for the search_id parameter, type <your_cursor_name>.
Select text/table for the Mime Type.
Click Try it out.
Table 2: Query Results sessionID
start_time
username
sourceip
category
1
2016-09-14 14:42:03
admin
9.23.121.97
16003
1
2016-09-14 14:42:09
admin
9.23.121.97
16003
2
2016-09-14 14:42:10
admin
127.0.0.1
16003
2
2016-09-14 14:42:11
admin
127.0.0.1
16003
3
2016-09-14 14:42:27
joe_blogs
9.23.121.98
16001
4
2016-09-14 14:44:11
joe_blogs
9.23.121.98
16001
5
2016-09-14 14:44:35
root
127.0.0.1
4017
5
2016-09-14 14:44:35
root
127.0.0.1
3014
5
2016-09-14 14:44:55
root
127.0.0.1
4017
5
2016-09-14 14:44:55
root
127.0.0.1
3014
The categories represent specific activities in your event logs. A new session is started for every change of user name and source IP address values, for example, see sessionid 2 and sessionid 5.
Also, a new session is created for category 16001, which occurs in sessionid 3 and sessionid 4.
Example
In this example events are returned and grouped by unique session ID, where the user joe_blogs logs in and starts a process between 4 PM and 11:30 PM on November 25.
select sessionId,DATEFORMAT(starttime,’YYYY-MM-dd HH:mm:ss’) start_time,username,sourceip,category from events into <cursor_name> where username=’joe_blogs’ SESSION BY starttime username,_sourceip BEGIN category=16001 END category=16003 start ’2016-11-25 16:00’ stop ’2016-11-25 23:30’
A session is started when you get an event where the BEGIN expression is met OR the previous event ends the session.
A session is ended when you get an event where the END expression is true OR the next event starts a new session.
Event category 16001 indicates a user login or logout event on the Console, and event category 16003 indicates that a user initiated a process, such as starting a backup or generating a report. For a list of event categories, see the Juniper Secure Analytics Administration Guide.
Transactional Query Refinements
Refine transactional AQL queries by using the EXPLICIT expression with the BEGIN and END expressions. Also, use the TIMEOUT and TIMEWINDOW expressions to specify time intervals.
Use the EXPLICIT expression with the BEGIN and END expressions to apply more precise filtering to your transactional queries.
For example, you might use the BEGIN expression with the EXPLICIT END expression to capture several (BEGIN) unsuccessful login attempts, which are followed by an (EXPLICIT END) successful login.
Use the TIMEOUT and TIMEWINDOW expressions to apply time filters for the sessions in your transactional queries.
- Expressions
- BEGIN and END Expressions
- EXPLICIT BEGIN and END Expressions
- BEGIN and EXPLICIT END
- EXPLICIT BEGIN and EXPLICIT END
- TIMEOUT
- TIMEWINDOW
Expressions
Use the expressions that are described in the following to refine your transactional AQL query:
Query expressions |
Description |
|---|---|
BEGIN |
A session is started when you get an event where the BEGIN expression is met or the previous event ends the session. |
EXPLICIT BEGIN |
Starts a new session only if the EXPLICIT BEGIN expression is true. |
END |
A session is ended when you get an event where the END expression is true or the next event starts a new session. |
EXPLICIT END |
Closes the current session only if the EXPLICIT END expression is true. |
TIMEOUT |
Closes the session when the specified TIMEOUT period elapses from the time that the previous event occurred to the time that the current event happened. |
TIMEWINDOW |
Tracks the session time. Closes the session when the specified TIMEWINDOW period elapses from the time that the first event occurred to the time that the current event happened. |
Syntax --SESSION BY <TimeExpression> <ExpressionList> [EXPLICIT] BEGIN <booleanExpression> [EXPLICIT] END <booleanExpression> TIMEOUT <IntegerLiteral millieseconds> TIMEWINDOW <IntegerLiteral SECONDS|MINUTES|HOURS|DAYS>
The following examples show the examples of results that you get by using different combinations of the available query expressions:
BEGIN and END Expressions
A BEGIN expression starts a session when an event matches the BEGIN expression or the previous event ends the session.
An END expression ends a session when the END expression is true for an event or the next event starts a new session.
By using the EXPLICIT expression with the BEGIN and END expressions, you apply a more precise filter that refines the result set.
See the following examples of queries and results.
The following query example uses BEGIN and END expressions.
Select sessionId, DATEFORMAT(starttime,’YYYY-MM-dd HH:mm:ss’) start_time, username, sourceip, category from events into TR1 where username = ’user_x’ SESSION BY starttime username, sourceip BEGIN category=16001 END category=16003 start ’2016-12-10 16:00’ stop ’2016-12-10 23:30’
Event category 16001 indicates a user login or logout event on the Console, and event category 16003 indicates that a user initiated a process, such as starting a backup or generating a report.
The following table shows the results for the query that uses BEGIN and END.
sessionID |
start_Time |
user name |
sourceip |
category |
|---|---|---|---|---|
1 |
2016-12-10 16:00:06 |
user_x |
10.2.2.10 |
16001 |
1 |
2016-12-10 16:00:06 |
user_x |
10.2.2.10 |
16003 |
2 |
2016-12-10 16:00:06 |
user_x |
10.2.2.10 |
16003 |
3 |
2016-12-10 16:00:10 |
user_x |
10.2.2.10 |
16001 |
3 |
2016-12-10 16:00:10 |
user_x |
10.2.2.10 |
16003 |
4 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16003 |
3 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16001 |
3 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16003 |
Sessionid 2 consists of only one event that closes it (category 16003). A session that has one event is an exception and can happen.
EXPLICIT BEGIN and END Expressions
Events are skipped when a session is not started and an event
is not an EXPLICIT BEGIN event.
Select sessionId, DATEFORMAT(starttime,’YYYY-MM-dd HH:mm:ss’) start_time, username, sourceip, category from events into TR2 where username=’user_x’ SESSION BY starttime username, sourceip EXPLICIT BEGIN category=16001 END category=16003 start ’2016-12-10 16:00’ stop ’2016-12-10 23:30’
The following table shows the results for the query that uses EXPLICIT BEGIN and END.
sessionID |
start_Time |
user name |
sourceip |
category |
|---|---|---|---|---|
1 |
2016-12-10 16:00:06 |
user_x |
10.2.2.10 |
16001 |
1 |
2016-12-10 16:00:06 |
user_x |
10.2.2.10 |
16003 |
2 |
2016-12-10 16:00:07 |
user_x |
10.2.2.10 |
16001 |
2 |
2016-12-10 16:00:07 |
user_x |
10.2.2.10 |
16003 |
3 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16001 |
3 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16003 |
3 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16003 |
4 |
2016-12-10 16:00:14 |
user_x |
10.2.2.10 |
16001 |
5 |
2016-12-10 16:00:15 |
user_x |
10.2.2.10 |
16001 |
5 |
2016-12-10 16:00:15 |
user_x |
10.2.2.10 |
16003 |
Only events that satisfy the EXPLICIT BEGIN expression are returned.
Sessionid 2 and Sessionid 4 in the EXPLICIT BEGIN and END don't
satisfy the EXPLICIT BEGIN expression.
BEGIN and EXPLICIT END
Close current session only if the EXPLICIT END expression is true. There are no more checks for BEGIN events in the session when the EXPLICIT END expression is true.
Multiple BEGIN events in a single session can be associated
with one EXPLICIT END expression. For example,
you might use the EXPLICIT END expression
for counting multiple failed login attempts that are followed by a
successful login during a specific time interval (session timeout).
The following query example uses BEGIN and EXPLICIT END expressions.
Select sessionId, DATEFORMAT(starttime,’YYYY-MM-dd HH:mm:ss’) start_time, username, sourceip, category from events into TR3 where username = ’user_x’ SESSION BY starttime username, sourceip BEGIN category=16001 EXPLICIT END category=16003 start ’2016-12-10 16:00’ stop ’2016-12-10 23:30’
The following table shows the results for the query that uses BEGIN and EXPLICIT END expressions.
sessionID |
start_Time |
user name |
sourceip |
category |
|---|---|---|---|---|
1 |
2016-12-10 16:00:06 |
user_x |
10.2.2.10 |
16001 |
1 |
2016-12-10 16:00:06 |
user_x |
10.2.2.10 |
16003 |
2 |
2016-12-10 16:00:07 |
user_x |
10.2.2.10 |
16003 |
2 |
2016-12-10 16:00:10 |
user_x |
10.2.2.10 |
16001 |
2 |
2016-12-10 16:00:10 |
user_x |
10.2.2.10 |
16003 |
3 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16001 |
3 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16003 |
4 |
2016-12-10 16:00:12 |
user_x |
10.2.2.10 |
16003 |
4 |
2016-12-10 16:00:12 |
user_x |
10.2.2.10 |
16001 |
4 |
2016-12-10 16:00:12 |
user_x |
10.2.2.10 |
16003 |
5 |
2016-12-10 16:00:13 |
user_x |
10.2.2.10 |
16001 |
4 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16003 |
EXPLICIT BEGIN and EXPLICIT END
Events are ignored when a session is not started and an event is not an EXPLICIT BEGIN event.
Close current session only if the EXPLICIT END expression is true. There are no more checks for BEGIN events in the session when the EXPLICIT END expression is true.
The following query example uses both EXPLICIT BEGIN and EXPLICIT END expressions.
Select sessionId, DATEFORMAT(starttime,’YYYY-MM-dd HH:mm:ss’) start_time, username, sourceip, category from events into TR4 where username = ’user_x’ SESSION BY starttime username, sourceip EXPLICIT BEGIN category=16001 EXPLICIT END category=16003 start ’2016-12-10 16:00’ stop ’2016-12-10 23:30’
The following table shows the results for the query that uses both EXPLICIT BEGIN and EXPLICIT END expressions.
sessionID |
start_Time |
user name |
sourceip |
category |
|---|---|---|---|---|
1 |
2016-12-10 16:00:06 |
user_x |
10.2.2.10 |
16001 |
1 |
2016-12-10 16:00:06 |
user_x |
10.2.2.10 |
16003 |
2 |
2016-12-10 16:00:10 |
user_x |
10.2.2.10 |
16001 |
2 |
2016-12-10 16:00:10 |
user_x |
10.2.2.10 |
16003 |
3 |
2016-12-10 16:00:11 |
user_x |
10.2.2.10 |
16001 |
3 |
2016-12-10 16:00:12 |
user_x |
10.2.2.10 |
16001 |
3 |
2016-12-10 16:00:12 |
user_x |
10.2.2.10 |
16003 |
4 |
2016-12-10 16:00:13 |
user_x |
10.2.2.10 |
16001 |
4 |
2016-12-10 16:00:14 |
user_x |
10.2.2.10 |
16001 |
4 |
2016-12-10 16:00:14 |
user_x |
10.2.2.10 |
16003 |
5 |
2016-12-10 16:00:15 |
user_x |
10.2.2.10 |
16001 |
5 |
2016-12-10 16:00:15 |
user_x |
10.2.2.10 |
16003 |
TIMEOUT
Closes the session when the specified TIMEOUT period elapses from the time that the previous event occurred to the time that the current event happened. The current event becomes part of a new session. The TIMEOUT value is specified in milliseconds.
The following query example uses the TIMEOUT expression.
Select sessionId, DATEFORMAT(starttime,’YYYY-MM-dd HH:mm:ss.SSS’) start_time, username, sourceip, category from events into TR5 where username=’user_x’ SESSION BY starttime username, sourceip BEGIN category=16001 EXPLICIT END category=16003 TIMEOUT 3600 start ’2016-12-10 16:00’ stop ’2016-12-10 23:30’
The following table shows the results for the query that uses the TIMEOUT expression.
sessionID |
start_Time |
user name |
sourceip |
category |
|---|---|---|---|---|
1 |
2016-12-10 16:00:06.716 |
user_x |
10.2.2.10 |
16003 |
2 |
2016-12-10 16:00:10.328 |
user_x |
10.2.2.10 |
16001 |
Sessionid 1 is ended and sessionid 2 is started because the TIMEOUT of 3600 is exceeded.
TIMEWINDOW
Tracks the session time. Closes the session when the specified TIMEWINDOW period elapses from the time that the first event occurred to the time that the current event happened. The current event becomes part of a new session. The TIMEWINDOW value can be specified in seconds, minutes, hours, or days.
The following query example uses the TIMEWINDOW expression.
Select sessionId, DATEFORMAT(starttime,’YYYY-MM-dd HH:mm:ss.SSS’) start_time, username, sourceip, category from events into TR6 where username=’user_x’ SESSION BY starttime _username, sourceip BEGIN category=16001 EXPLICIT END category=16003 TIMEWINDOW 3000 start ’2016-12-10 16:00’ stop ’2016-12-10 23:30’
The following table shows the results for the query that uses the TIMEWINDOW expression.
sessionID |
start_Time |
user name |
sourceip |
category |
|---|---|---|---|---|
1 |
2016-12-10 16:00:06.415 |
user_x |
10.2.2.10 |
16001 |
1 |
2016-12-10 16:00:06.433 |
user_x |
10.2.2.10 |
16003 |
2 |
2016-12-10 16:00:06.716 |
user_x |
10.2.2.10 |
16003 |
3 |
2016-12-10 16:00:10.328 |
user_x |
10.2.2.10 |
16001 |
3 |
2016-12-10 16:00:06.328 |
user_x |
10.2.2.10 |
16003 |
Sessionid 1 is within the TIMEWINDOW expression time but sessionid 2 is ended because the TIMEWINDOW of 3600 is exceeded.