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:

humio
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 e.g. a maximum pause of 5 minutes between HTTP accesses like this:

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

The implied parameter is collect.

Examples

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

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

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

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

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

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

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

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