Extends the groupBy()
function for grouping by time,
diving the search time interval into buckets. Each event is put into a
bucket based on its timestamp.
When using the bucket()
function, events are grouped
by a number of notional 'buckets', each defining a timespan, calculated by
dividing the time range by the number of required buckets. The function
creates a new field, _bucket, that
contains the corresponding bucket's start time in milliseconds (UTC time).
The bucket()
function accepts the same parameters as
groupBy()
.
The output from the bucket()
is a table and can be
used as the input for a variety of
Widgets. Alternatively, use the
timeChart()
function.
Parameter | Type | Required | Default Value | Description |
---|---|---|---|---|
buckets | number | optional[a] | Defines the number of buckets. The time span is defined by splitting the query time interval into this many buckets. 0..1500 | |
Minimum | 1 | |||
field | string | optional[a] | Specifies which fields to group by. Notice that it is possible to group by multiple fields. | |
function | array of aggregate functions | optional[a] | count(as=_count) | Specifies which aggregate functions to perform on each group. Default is to count the elements in each group. If several aggregators are listed for the function parameter, then their outputs are combined using the rules described for stats() . |
limit | integer | optional[a] | 10 | Defines the maximum number of series to produce. A warning is produced if this limit is exceeded, unless the parameter is specified explicitly. |
Maximum | 500 | |||
minSpan | long | optional[a] | It sets the minimum allowed span for each bucket, for cases where the buckets parameter has a high value and therefore the span of each bucket can be so small as to be of no use. It is defined as a Relative Time Syntax such as 1hour or 3 weeks . minSpan can be as long as the search interval at most — if set as longer instead, a warning notifies that the search interval is used as the minSpan . | |
span [b] | relative-time | optional[a] | auto | Defines the time span for each bucket. The time span is defined as a relative time modifier like 1hour or 3 weeks . If not provided or set to auto the search time interval, and thus the number of buckets, is determined dynamically. |
timezone | string | optional[a] | Defines the time zone for bucketing. This value overrides timeZoneOffsetMinutes which may be passed in the HTTP/JSON query API. For example, timezone=UTC or timezone='+02:00' . See the full list of timezones supported by LogScale at Supported Time Zones. | |
unit | array of strings | optional[a] | Each value is a unit conversion for the given column. For instance: bytes/span to Kbytes/day converts a sum of bytes into Kb/day automatically taking the time span into account. If present, this array must be either length 1 (apply to all series) or have the same length as function . | |
[a] Optional parameters use their default value unless explicitly set. |
When generating aggregated buckets against data, the exact number of buckets may not match the expected due to the combination of the query span, requested number of buckets, and available event data.
For example, given a query displaying buckets for every one minute, but with a query interval of 1 hour starting at 09:17:30, 61 buckets will be created, as represented by the shaded intervals shown in Figure 109, “Bucket Allocation using bucket()”:
Figure 109. Bucket Allocation using bucket()
The buckets are generated, first based on the requested timespan interval or number of buckets, and then on the relevant timespan boundary. For example:
An interval per hour across a day will start at 00:00
An interval of a minute across an hour will start at 09:00:00
Buckets will contain the following event data:
The first bucket will contain the extracted event data for the relevant timespan (1 bucket per minute from 09:17), but only containing events after query interval. For example, the bucket will start 09:17, but contain only events with a timestamp after 09:17:30
The next 58 buckets will contain the event data for each minute.
Bucket 60 will contain the event data up until 10:17:30.
Bucket 61 will contain any remaining data from the last time interval bucket.
The result is that the number of buckets returned will be 61, even though
the interval is per minute across a one hour boundary. The trailing data
will always be included in the output. It may have an impact on the data
displayed when bucket()
is used in combination with a
Time Chart
.
bucket()
Examples
Click
next to an example below to get the full details.
Aggregate Status Codes by count()
per Minute
Aggregate Status Codes by count()
Per Minute
Time series aggregate status codes by count()
per minute into buckets
Bucket Counts When Using bucket()
Bucket Events Into Groups
Bucket events into 24 groups using the count()
function and buckets()
function
Bucket Events Summarized by count()
Count Events per Repository
Count of the events received by repository