Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

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.

  1. 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.

  2. To test an example, take the following steps:
    1. To go to the JSA API documentation page, from the Help menu, click Interactive API for Developers.

    2. Click 8.0 or the highest version to expand the menu.

    3. Click /ariel >/searches.

    4. Click the Post tab.

    5. Enter your AQL query in the Value field for the query_expression parameter.

      For example,

      The <your_cursor_name> is any name that you want to use for the results output.

    6. Click Try it out.

      If the query runs without errors, the response code is 201.

    7. Click /ariel >/ searches > >/{search_id} >/results

      The 8.0 - GET - /ariel/searches/{search_id}/results page opens.

    8. In the Value field for the search_id parameter, type <your_cursor_name>.

    9. Select text/table for the Mime Type.

    10. 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.

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

Use the expressions that are described in the following to refine your transactional AQL query:

Table 3: AQL Transactional Query Expressions

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.

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.

Table 4: BEGIN and END Query Results

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

Note

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.

The following table shows the results for the query that uses EXPLICIT BEGIN and END.

Table 5: EXPLICIT BEGIN and END Query Results

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.

The following table shows the results for the query that uses BEGIN and EXPLICIT END expressions.

Table 6: BEGIN and EXPLICIT END Query Results

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.

The following table shows the results for the query that uses both EXPLICIT BEGIN and EXPLICIT END expressions.

Table 7: EXPLICIT BEGIN and EXPLICIT END Query Results

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.

The following table shows the results for the query that uses the TIMEOUT expression.

Table 8: TIMEOUT Query Results

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.

The following table shows the results for the query that uses the TIMEWINDOW expression.

Table 9: TIMEWINDOW Query Results

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.