bin

Bucket timestamps or numeric values into discrete bins for aggregation and analysis.

Description

The bin command groups continuous values into discrete buckets, making it easier to analyze patterns over time or numeric ranges. This is essential for time-windowed detection rules, histograms, and trend analysis.

For time-based binning, events are grouped into time intervals (e.g., 5 minutes, 1 hour). For numeric binning, values are grouped into ranges (e.g., 0-1000, 1000-2000).

The binned field can then be used with stats to aggregate data within each bucket.

Syntax

Time-based binning:

... | bin span=<duration> [hop=<duration>] [sliding] [<field>] [as <alias>]

Numeric binning:

... | bin <field> span=<number> [as <alias>]

Required Arguments

span Syntax: span=<duration> or span=<number> Description: Size of each bucket. For time: duration like 5m, 1h, 1d. For numeric: a number like 1000, 5000.

Optional Arguments

field Syntax: <field> or field=<field> Description: Field to bin. Defaults to timestamp for time-based binning. Required for numeric binning.

as Syntax: as <alias> Description: Name for the output field. Defaults to time_bucket for time bins or the original field name for numeric bins.

hop Syntax: hop=<duration> Description: Creates overlapping hop windows. Windows of size span advance by hop interval. Events belong to multiple windows.

sliding Syntax: sliding Description: Creates sliding windows where each event starts its own window of duration span.

Window Types

Tumbling Windows (Default)

Events belong to exactly one window. Non-overlapping, fixed-size intervals.

| bin span=1h

Window 1: [00:00 - 01:00)
Window 2: [01:00 - 02:00)
Window 3: [02:00 - 03:00)

Hop Windows

Windows overlap. Each event belongs to multiple windows (span/hop windows). Useful for alerting: "alert if >100 events in any rolling 1-hour window, checked every 5 minutes."

| bin span=1h hop=5m

Window 1: [00:00 - 01:00)
Window 2: [00:05 - 01:05)
Window 3: [00:10 - 01:10)
...

An event at 00:30 belongs to windows starting at 00:00, 00:05, 00:10, ..., 00:30.

Sliding Windows

Every event defines its own window start. The window extends from the event's timestamp to timestamp + span.

| bin span=1h sliding

Each row gets a time_bucket (start) and time_bucket_end (end) field.

Time Duration Units

Examples

Time-based binning (5 minute intervals)

* | bin span=5m
  | stats count() by time_bucket

Groups events into 5-minute buckets and counts events in each.

Detect brute force with time windows

action=login status=failure
| bin span=10m
| stats count() as failures by time_bucket, src_ip
| where failures > 5

Identifies IPs with more than 5 failed logins in any 10-minute window.

Rolling alert with hop windows

action=login status=failure
| bin span=1h hop=5m
| stats count() as failures by time_bucket, src_ip
| where failures > 100

Detects >100 failed logins in any rolling 1-hour window, evaluated every 5 minutes. More sensitive than tumbling windows because it catches bursts that span window boundaries.

Hourly traffic analysis

* | bin span=1h
  | stats sum(bytes) as total_bytes by time_bucket

Calculates total bytes transferred per hour.

Custom time field

* | bin span=15m field=last_login as login_bucket
  | stats dc(user) by login_bucket

Bins a custom timestamp field into 15-minute intervals.

Numeric binning for bytes

* | bin bytes span=1000000 as mb_bucket
  | stats count() by mb_bucket

Groups events by megabyte ranges (0-1MB, 1-2MB, etc.).

Response time histogram

* | bin response_time span=100 as time_bucket
  | stats count() by time_bucket
  | sort time_bucket

Creates a histogram of response times in 100ms buckets.

Port scan detection with hop windows

* | bin span=5m hop=1m
  | stats dc(dest_port) as unique_ports by time_bucket, src_ip
  | where unique_ports > 50

Detects port scanning with rolling 5-minute windows checked every minute.

Daily aggregation

* | bin span=1d
  | stats count() as events,
         dc(user) as unique_users,
         sum(bytes) as total_bytes
  by time_bucket

Daily summary statistics.

Data exfiltration detection

* | bin span=5m hop=1m
  | stats sum(bytes_out) as outbound by time_bucket, src_ip
  | where outbound > 100000000

Detects large data transfers (>100MB in any 5-minute window) with minute granularity.

Multi-stage detection

process_name="powershell.exe"
| bin span=5m
| stats count() as executions,
        dc(src_host) as unique_hosts
  by time_bucket
| where executions > 10 AND unique_hosts > 5

Detects widespread PowerShell execution across multiple hosts.

Stat of a stat with hop windows

* | bin span=1h hop=5m
  | stats count() as hourly_count by time_bucket, src_ip
  | eval traffic_light = if(hourly_count < 50, "Green", if(hourly_count > 100, "Red", "Yellow"))
  | where traffic_light != "Green"
  | stats count() as alert_count, values(src_ip) as ips by time_bucket, traffic_light

Multi-stage search with overlapping windows for frequency analysis.

Usage Notes

Time alignment: Tumbling window buckets align to standard intervals (e.g., 5m aligns to :00, :05, :10, etc.).

Hop window output: Hop windows add both time_bucket (window start) and time_bucket_end (window end) fields.

Event multiplication: With hop windows, each event appears in multiple rows (one per window it belongs to). Plan for increased result size.

Numeric binning: Only supports tumbling windows. Hop and sliding are for time-based binning only.

Performance: Tumbling windows are most efficient. Hop windows multiply data by span/hop factor.

Span selection: For hop windows, choose span based on your detection window and hop based on desired granularity.

Related Commands

• stats - Aggregate data within bins
• timechart - Time-based aggregation with automatic binning
• where - Filter binned results
• sort - Order results by time bucket
• anomaly - Statistical outlier detection