series( ) Query Function

Collects a series of values for the selected fields from multiple events into one (or more) events. Combined with groupBy(), this can be used to gather data from transactions by some identity field.

For example, given an access log, you can collect the series of methods for a given url like this:

   url="/some/url" | series([method], separator=";")

which produces a single event:

field example description
@timestamp 145245466 Timestamp of the first event arriving.
_duration 1245 Timespan (in milliseconds) of the series of events included in this series. If the series contains just one field value the value of _duration will be 0.
method GET;POST;GET;GET;DELETE Time-ordered series of values for the method field.

Because the value of the collected fields may be rather large, the memory consumption of this function can be controlled using the memlimit parameter.

Using the similar data source as above, you can also emit a single event for each user “visit” as defined above by e.g. a maximum pause of 5 minutes between HTTP accesses like this:

url="/some/url" | series([method], separator=";", maxpause=5min)

which may produce two (or more) events:

field example description
@timestamp 145245466 Timestamp of the first event arriving.
_duration 512 Timespan (in milliseconds) of the series of events included in this series. If the series contains just one field value the value of _duration will be 0.
method GET;POST;GET Time-ordered series of values for the method field.
field example description
@timestamp 149256978 Timestamp of the first event in the second “batch”.
_duration 251 Timespan (in milliseconds) of the series of events included in this series.
method GET;DELETE Time-ordered series of values for the method field in the second “batch”.

Because this function can use a lot of memory to gather all the data making up the collected field values, it controls memory usage at runtime using the memlimit parameter. Read more about that below.

Parameters

Name Type Required Default Description
collect [string] Yes Names of the fields to keep.
separator string No String used to separate multiple values.
maxpause string No Maximum time between events in a transaction (e.g. 10s), specified as a relative time modifier.
maxduration string No Maximum duration of a transaction (e.g. 5min), specified as a relative time modifier.
startmatch Filter No A filter query inside {} to match the start of a transaction (applied to the event as a whole), e.g. { /session end:/ }.
endmatch Filter No A filter query inside {} to match the end of a transaction (applied to the event as a whole), e.g. { /session end:/ }.
memlimit string No Limit on number of bytes of memory consumed by each series invocation (defaults to 1KiB). When used with the parameters startmatch, endmatch, maxpause and maxduration to produce multiple sub-series, this parameter controls the memory usage of the entire sequence of series, not each individual one. When series is used inside a groupBy(), this parameter only limits the memory consumption per group. So if the groupBy() is limited to 50,000 groups each using 1KB, the combined upper limit would be 50MB. The memlimit value is limited to 1KiB bytes by default and can be configured using the parameter MAX_SERIES_MEMLIMIT.

collect is the unnamed parameter.

Examples

In an access log, collect the series of methods used for a given url.

url="/some/url" | series([method], separator=";")

Aggregate series of website visits, each visitor defined as non-active after 1 minute.

groupBy(client_ip, function=series(maxpause=1m, collect=[url], memlimit=1KB))

Aggregate series of auth logs, starting a new series for each login attempt.

groupBy(userID, function=series(collect=[@rawstring], startmatch={ /Login attempt:/ }))

Aggregate series of auth logs, ending each series with a failed login attempt.

groupBy(userID, function=series(collect=[@rawstring], endmatch={ /Failed Login/ }))