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.

ParameterTypeRequiredDefaultDescription
collect[a]Array of stringsrequired  Names of the fields to keep.
endmatchFilteroptional[b]  A filter query inside {} to match the end of a transaction (applied to the event as a whole), e.g. { /session end:/ }. Even with this parameter specified, "partial" sessions which do not include an end event are output — unlike what happens with the startmatch parameter, endmatch does not cause any event to be ignored.
maxdurationrelative-timeoptional[b]  Maximum duration of a transaction (e.g. 5min), specified as a Relative Time Syntax.
maxpauserelative-timeoptional[b]  Maximum time between events in a transaction (e.g. 10s), specified as a Relative Time Syntax.
memlimitstringoptional[b]  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.
separatorstringoptional[b]\n String used to separate multiple values.
startmatchFilteroptional[b]  A filter query inside {} to match the start of a transaction (applied to the event as a whole), e.g. { /session start:/ }. With this parameter specified, any event coming before the first start event, or in between an end event and the start event that follows, is not part of any session and is therefore ignored — all sessions include exactly one start event.

[a] The argument name collect can be omitted.

[b] Optional parameters use their default value unless explicitly set

Omitted Argument Names

The argument name for collect can be omitted; the following forms of this function are equivalent:

logscale
series("value")

and:

logscale
series(collect="value")

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

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

This 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, for example, a maximum pause of 5 minutes between HTTP accesses like this:

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

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

series() Examples

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

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

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

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

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

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

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

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