head command overview

The SPL2 head command returns the first search results, in search order, based on the <limit> specified. For historical searches, returns the most recent events. For real-time searches, searches the first captured events.

If no options are explicitly specified, the head command returns the first 10 results.

Syntax

The required syntax is in bold.

head

[keeplast = (true | false)]

[while "("<boolean-expression>")"]

[<limit>]

How the SPL2 head command works

The SPL2 head command returns the top <limit> results. If your search returns events, the most recent events are returned first.

Here is an example of some search results:

Time	Event
00:15:07 AM 17 Sep 2021	Thu Sep 17 2021 00:15:07 mailsv1 sshd[5276]: Failed password for invalid user zhang from 194.8.74.23 port 3351 ssh2
11:59:07 PM 16 Sep 2021	Wed Sep 16 2021 23:59:07 mailsv1 sshd[5258]: Failed password for invalid user garcia from 194.8.74.23 port 3626 ssh2
11:12:33 PM 16 Sep 2021	Wed Sep 16 2021 23:12:33 mailsv1 sshd[21881]: pam_unix(sshd:session): session closed for user sullivan by (uid=0)
10:19:07 PM 16 Sep 2021	Wed Sep 16 2021 22:19:07 mailsv1 sshd[3760]: Failed password for invalid user dubois from 194.8.74.23 port 2472 ssh2
8:59:24 PM 16 Sep 2021	Wed Sep 16 2021 20:59:24 mailsv1 sshd[5801]: Failed password for invalid user patel from 194.8.74.23 port 2285 ssh2
8:42:07 PM 16 Sep 2021	Wed Sep 16 2021 20:42:07 mailsv1 sshd[3759]: Failed password for martin from 194.8.74.23 port 3769 ssh2
7:49:13 PM 16 Sep 2021	Wed Sep 16 2021 19:49:13 mailsv1 sshd[5979]: Failed password for invalid user garcia from 194.8.74.23 port 3417 ssh2

To see the first 3 events, you specify this:

... | head 3

You would see this set of events:

Time	Event
00:15:07 AM 17 Sep 2021	Thu Sep 17 2021 00:15:07 mailsv1 sshd[5276]: Failed password for invalid user zhang from 194.8.74.23 port 3351 ssh2
11:59:07 PM 16 Sep 2021	Wed Sep 16 2021 23:59:07 mailsv1 sshd[5258]: Failed password for invalid user garcia from 194.8.74.23 port 3626 ssh2
11:12:33 PM 16 Sep 2021	Wed Sep 16 2021 23:12:33 mailsv1 sshd[21881]: pam_unix(sshd:session): session closed for user sullivan by (uid=0)

Specifying a filter with the head command

Instead of returning just the top <limit> events, you can filter which events are returned by using the while argument. In this example is looking for events where the user is garcia and returns at most 5 events. The while argument is a <boolean-expression> that must be enclosed in parenthesis.

...| head while (user=garcia) 5

Here are the results:

Time	Event
11:59:07 PM 16 Sep 2021	Wed Sep 16 2021 23:59:07 mailsv1 sshd[5258]: Failed password for invalid user garcia from 194.8.74.23 port 3626 ssh2
7:49:13 PM 16 Sep 2021	Wed Sep 16 2021 19:49:13 mailsv1 sshd[5979]: Failed password for invalid user garcia from 194.8.74.23 port 3417 ssh2

To learn about the other arguments you can specify with the head command, see head command syntax details.

Using the command on transformed data

In the previous examples we show examples with search results that are events. You can also use the head command after the events have been summarized using a transforming command like stats.

Consider these results:

status	host	count
200	www1	11835
200	www2	11186
200	www3	11261
400	www1	233
400	www2	257
400	www3	211
403	www2	228
404	www1	244
404	www2	209

These results are sorted by the status field. If you specify something like ...| head 4 the first 4 results are returned:

status	host	count
200	www1	11835
200	www2	11186
200	www3	11261
400	www1	233

If you want return the top 4 results based on the count field, you must first sort the results by that field before you run the head command. For example:

...| sort count | head 4

status	host	count
200	www1	11835
200	www2	11186
200	www3	11261
400	www2	257

Compare the last result (257) with the last result in previous example (233) to see the difference.

Here is another example.

You want to group the results by host. When you sort on the host field and return the top 4 results, you get this:

status	host	count
200	www1	11835
400	www1	233
404	www1	244
200	www2	11186

See also

head command

head command syntax details

head command usage

head command examples