bin
Put events into fixed time buckets or numeric ranges, including hopping and sliding time windows, before you aggregate.
Use bin to place your events into time buckets or numeric ranges before you aggregate them. bucket is an alias.
Syntax
... | bin [<field>] span=<duration | number> [hop=<duration>] [sliding] [as <name>]| Option | Description |
|---|---|
field | The field to bucket. Write it before or after span=, or as field=<name>. Without a field, bin buckets time. |
span | Bucket size. For time: a number plus s, m, h or d (5m, 1h). For a numeric field: a number (1000). |
hop | Hopping windows: windows of length span that start every hop. Each event lands in every window that covers it. |
sliding | One window per event, from the event's time to time + span. |
as | Name of the output column. |
How it works
Where the bucket goes depends on how you call bin:
| Call | Output |
|---|---|
bin span=5m | Adds time_bucket (the bucket start). time is unchanged. |
bin time span=5m | Replaces time with the bucket start. |
bin time span=5m as tw | Adds tw. time is unchanged. |
bin http_response.length span=1000 | Replaces the field with the lower edge of its range (0, 1000, 2000 …). |
bin http_response.length span=1000 as size | Adds size. |
bin span=1h hop=15m | Adds time_bucket and time_bucket_end. Each event appears once per overlapping window (four times here). time is removed. |
bin span=1h sliding | Adds time_bucket (the event time) and time_bucket_end (time + span). |
Time buckets align to the clock: span=5m starts at :00, :05, :10.
Examples
Logon failures per user in 10-minute buckets:
class_uid=3002 status_id=2 | bin span=10m | stats count as failures by time_bucket, user.name | where failures > 20Bytes sent per source IP per hour:
class_uid=4002 | bin time span=1h | stats sum(traffic.bytes_out) as sent_bytes by time, src_endpoint.ipDistribution of HTTP response sizes in 10 KB ranges:
class_uid=4002 | bin http_response.length span=10000 as size_range | stats count by size_range | sort size_rangeHourly logon counts per user, scored for outliers (run over several days so each user has enough buckets):
class_uid=3002 | bin span=1h | stats count as logons by time_bucket, user.name | anomaly field=logons by user.name threshold=3One-hour windows advancing every 15 minutes, for brute-force detection that doesn't miss bursts split across a bucket boundary:
class_uid=3002 status_id=2 | bin span=1h hop=15m | stats count as failures by time_bucket, src_endpoint.ip | where failures > 50Notes
- For a chart of counts over time, timechart is shorter:
timechart span=10m count by user.name. - Hopping and sliding windows expose
time_bucket_endfor later grouping and filtering. The window end istime_bucketplusspan.