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 190, “Bucket Allocation using bucket()”:
![]() |
Figure 190. 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()
Compute Cumulative Aggregation Across Buckets
Compute a cumulative aggregation across buckets using the accumulate()
function with timeChart()
Count Events per Repository
Count of the events received by repository