Collects events into sessions, which are series of events that
are no further than
maxpause apart
(defaults to 15m), and then performs an aggregate operation
across the events that make up the session.
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
function[a] | array of aggregate functions | optional[b] | count(as=_count) | Specifies which aggregate functions to perform on each session. If several aggregators are listed for the function parameter, then their outputs are combined using the rules described for stats(). |
maxpause | string | optional[b] | 15m | Defines the maximum pause between sessions, for example, events more than this far apart will become separate sessions. |
[b] Optional parameters use their default value unless explicitly set. | ||||
Hide omitted argument names for this function
Omitted Argument NamesThe argument name for
functioncan be omitted; the following forms of this function are equivalent:logscale Syntaxsession("value")and:
logscale Syntaxsession(function="value")These examples show basic structure only.
session()Examples
Click next to an example below to get the full details.
Analyze User Sessions Based on Click Activity
Analyzes user sessions based on users click activity using the
session() function
Query
groupBy(cookie_id, function=session(maxpause=15m, count(as=clicks)))
| sort(clicks)Introduction
In this example, the session() function is used to
analyze user sessions based on users click activity. The
session() function groups events by a given
timespan.
Example incoming data might look like this:
| timestamp | cookie_id | action_type | page_url | user_agent |
|---|---|---|---|---|
| 2025-05-15 05:30:00 | user123 | pageview | /home | Mozilla/5.0 (Windows NT 10.0; Win64; x64) |
| 2025-05-15 05:30:15 | user123 | click | /products | Mozilla/5.0 (Windows NT 10.0; Win64; x64) |
| 2025-05-15 05:30:30 | user123 | click | /product/item1 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) |
| 2025-05-15 05:31:00 | user123 | click | /cart | Mozilla/5.0 (Windows NT 10.0; Win64; x64) |
| 2025-05-15 05:31:30 | user123 | click | /checkout | Mozilla/5.0 (Windows NT 10.0; Win64; x64) |
| 2025-05-15 05:35:00 | user456 | pageview | /home | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) |
| 2025-05-15 05:35:30 | user456 | click | /about | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) |
| 2025-05-15 05:36:00 | user456 | click | /contact | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) |
| 2025-05-15 05:38:00 | user789 | pageview | /home | Mozilla/5.0 (iPhone; CPU iPhone OS 14_0) |
| 2025-05-15 05:38:30 | user789 | click | /products | Mozilla/5.0 (iPhone; CPU iPhone OS 14_0) |
Step-by-Step
Starting with the source repository events.
- logscale
groupBy(cookie_id, function=session(maxpause=15m, count(as=clicks)))Groups events by the field cookie_id (unique user identifier) and creates sessions with 15-minute inactivity timeout (the default value of the
maxpauseparameter), then makes a count of each event in a session returning the result in a new field named clicks. - logscale
| sort(clicks)Sorts the results by number of clicks (default is descending order).
Event Result set.
Summary and Results
The query is used to analyze user sessions based on the users click activity. The query is useful, for example, to identify most/least active user sessions, detect potential automated behavior or just to understand user engagement levels.
Sample output from the incoming example data:
| cookie_id | clicks |
|---|---|
| user123 | 5 |
| user456 | 3 |
| user789 | 2 |
Note that each row represents an event (either pageview or click).
Count Unique Visitors Based on Client IP Addresses
Count unique visitors based on client IP addresses using the
session() function
Query
groupBy(client_ip, function=session(maxpause=15m))
| count()Introduction
In this example, the session() function is used to
count the unique visitors (each visitor defined as non-active for 15
minutes) of a site based on client IP addresses. The
session() function groups events by a given
timespan.
Example incoming data might look like this:
| timestamp | client_ip | url | status_code | user_agent |
|---|---|---|---|---|
| 2025-05-15 05:30:00 | 192.168.1.100 | /login | 200 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) |
| 2025-05-15 05:31:15 | 192.168.1.100 | /dashboard | 200 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) |
| 2025-05-15 05:32:30 | 192.168.1.100 | /reports | 200 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) |
| 2025-05-15 05:48:00 | 192.168.1.100 | /login | 200 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) |
| 2025-05-15 05:30:05 | 192.168.1.101 | /login | 200 | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) |
| 2025-05-15 05:35:10 | 192.168.1.101 | /profile | 200 | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) |
| 2025-05-15 05:40:00 | 192.168.1.102 | /login | 200 | Mozilla/5.0 (iPhone; CPU iPhone OS 14_0) |
| 2025-05-15 05:41:30 | 192.168.1.102 | /settings | 200 | Mozilla/5.0 (iPhone; CPU iPhone OS 14_0) |
| 2025-05-15 05:42:45 | 192.168.1.102 | /logout | 200 | Mozilla/5.0 (iPhone; CPU iPhone OS 14_0) |
Step-by-Step
Starting with the source repository events.
- logscale
groupBy(client_ip, function=session(maxpause=15m))Groups events by the field client_ip into sessions of 15 minutes. then makes a count of the total number of unique sessions
The
maxpauseparameter defines the maximum pause between the sessions (15min this example). Events more far apart than the defined value will become seperate sessions. For example, if the same user returns to a site within 15 minutes, it will be the same session. - logscale
| count()Makes a count of the total number of unique sessions.
Event Result set.
Summary and Results
The query is used to group events by client IP addresses into sessions of 15m, and then make a count of the total number of unique sessions (returns the total count of sessions across all IP addresses). The query is, for example, useful for measuring unique website/application visitors and understanding real user engagement patterns. Also useful for security monitoring and detection of unusual spikes in unique visitors.
Sample output from the incoming example data:
| _count |
|---|
| 4 |
The query counts 4 unique sessions total as the first IP address has activity that spans beyond the 15-minute session timeout, creating two distinct sessions.
If you make the count on the client_ip field:
| count(client_ip), the query will return a more detailed
result showing the session count per IP address:
| client_ip | _count |
|---|---|
| 192.168.1.100 | 2 |
| 192.168.1.101 | 1 |
| 192.168.1.102 | 1 |
Find Minimum And Maximum Values of any Numerical Field in Session
Find minimum and maximum values of any numerical field in a
session using the session() function
Query
groupBy(cookie_id, function=session([max(bet),min(bet)]))Introduction
In this example, the session() function is used to
find minimum and maximum values of the field bet in
a session. The session() function groups events by
a given timespan.
Example incoming data might look like this:
| timestamp | cookie_id | bet | action_type | category |
|---|---|---|---|---|
| 2025-05-15 05:30:00 | user123 | 25.99 | purchase | electronics |
| 2025-05-15 05:32:00 | user123 | 49.99 | purchase | electronics |
| 2025-05-15 05:34:00 | user123 | 15.99 | purchase | accessories |
| 2025-05-15 05:48:00 | user123 | 99.99 | purchase | appliances |
| 2025-05-15 05:49:00 | user123 | 150.00 | purchase | furniture |
| 2025-05-15 05:35:00 | user456 | 75.50 | purchase | clothing |
| 2025-05-15 05:37:00 | user456 | 199.99 | purchase | appliances |
| 2025-05-15 05:40:00 | user456 | 89.99 | purchase | electronics |
| 2025-05-15 05:30:00 | user789 | 10.99 | purchase | books |
| 2025-05-15 05:55:00 | user789 | 20.99 | purchase | books |
Step-by-Step
Starting with the source repository events.
- logscale
groupBy(cookie_id, function=session([max(bet),min(bet)]))Groups events by the field cookie_id (unique user identifier) and creates sessions of 15-minutes timeout (the default value of the
maxpauseparameter), then calculates the maximun and minimum values of the field bet for each session, returning the results in new fields named _max and _min. Event Result set.
Summary and Results
The query is used to analyze the likelihood (the bet) of the behavior within user sessions. This query is, for example, useful for identifying if the event was an attempt to hack the system.
Sample output from the incoming example data:
| cookie_id | _max | _min |
|---|---|---|
| user123 | 49.99 | 15.99 // First session |
| user123 | 150.00 | 99.99 // Second session |
| user456 | 199.99 | 75.50 // Single session |
| user789 | 10.99 | 10.99 // First session |
| user789 | 20.99 | 20.99 // Second session |
Note that each session shows its own min/max values.