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.

About this task

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.

Procedure

  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 IBM® QRadar® 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, 
      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.

    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.

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 IBM QRadar Administration Guide.