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.
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
collect[a] | array of strings | required | Names of the fields to keep. | |
endmatch | filter | optional[b] | A filter query inside {} to match the end of a transaction (applied to the event as a whole), for example, { /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. | |
maxduration | relative-time | optional[b] | Maximum duration of a transaction (for example, 5min), specified as a Relative Time Syntax. | |
maxpause | relative-time | optional[b] | Maximum time between events in a transaction (for example, 10s), specified as a Relative Time Syntax. | |
memlimit | string | optional[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. | |
| Minimum | 1 | |||
separator | string | optional[b] | \n | String used to separate multiple values. |
startmatch | filter | optional[b] | A filter query inside {} to match the start of a transaction (applied to the event as a whole), for example, { /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. | |
[b] Optional parameters use their default value unless explicitly set. | ||||
Hide omitted argument names for this function
Omitted Argument NamesThe argument name for
collectcan be omitted; the following forms of this function are equivalent:logscale Syntaxseries(["value"])and:
logscale Syntaxseries(collect=["value"])These examples show basic structure only.
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=";")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:
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.
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/ }))