bin command overview, syntax, and usage
The SPL2 bin command puts continuous numerical values into discrete sets, or bins, by adjusting the value of <field> so that all of the items in a particular set have the same value.
The SPL2 bin command is automatically called by the SPL2 timechart command. Use the bin command for only statistical operations that the timechart command cannot process.
How the SPL2 bin command works
Use the SPL2 bin command to group events by the numerical values in a field. Consider the following timestamps:
| Event number | _time | Hour and minute | Minutes from first time |
|---|---|---|---|
| 1 | 22 Aug 2024 01:56:37 AM | 01:56 | |
| 2 | 22 Aug 2024 01:58:21 AM | 01:58 | 2 minutes |
| 3 | 22 Aug 2024 01:59:59 AM | 01:59 | 3 minutes |
| 4 | 22 Aug 2024 02:03:16 AM | 02:03 | 7 minutes |
| 5 | 22 Aug 2024 02:05:43 AM | 02:05 | 9 minutes |
| 6 | 22 Aug 2024 02:09:38 AM | 02:09 | 13 minutes |
| 7 | 22 Aug 2024 02:12:31 AM | 02:12 | 16 minutes |
You decide to run a search that bins the search results using a 5 minute time span on the _time field.
...| bin span=5m _time
The bin command groups the timestamps in the _time field into 5 minutes intervals. The groups are:
| Group | Timestamps from _time | Timestamp span range for each bin |
|---|---|---|
| 1 | 22 Aug 2024 01:56:37 AM 22 Aug 2024 01:58:21 AM |
22 Aug 2024 01:56:37 AM --- 22 Aug 2024 02:01:36 AM |
| 2 | 22 Aug 2024 02:03:16 AM 22 Aug 2024 02:05:43 AM |
22 Aug 2024 02:01:37 AM --- 22 Aug 2024 02:06:36 AM |
| 3 | 22 Aug 2024 02:09:38 AM | 22 Aug 2024 02:07:37 AM --- 22 Aug 2024 02:11:36 AM |
| 4 | 22 Aug 2024 02:12:31 AM | 22 Aug 2024 02:11:37 AM --- 22 Aug 2024 02:16:36 AM |
For searching purposes only, the bin command adjusts the value of _time so that all of the results use the same _time value. Commands in your search that come after the bin command will use this temporary value for _time.
The temporary timestamps for subsequent commands are the first timestamp in the span range, unless you specify a snap-to time.
| Group | Timestamps from _time | Timestamp span range for each bin | Timestamps for subsequent commands |
|---|---|---|---|
| 1 | 22 Aug 2024 01:56:37 AM 22 Aug 2024 01:58:21 AM |
22 Aug 2024 01:56:37 AM --- 22 Aug 2024 02:01:36 AM | 22 Aug 2024 01:56:37 AM |
| 2 | 22 Aug 2024 02:03:16 AM 22 Aug 2024 02:05:43 AM |
22 Aug 2024 02:01:37 AM --- 22 Aug 2024 02:06:36 AM | 22 Aug 2024 02:01:37 AM |
| 3 | 22 Aug 2024 02:09:38 AM | 22 Aug 2024 02:07:37 AM --- 22 Aug 2024 02:11:36 AM | 22 Aug 2024 02:07:37 AM |
| 4 | 22 Aug 2024 02:12:31 AM | 22 Aug 2024 02:11:37 AM --- 22 Aug 2024 02:16:36 AM | 22 Aug 2024 02:11:37 AM |
The bin command is frequently used in a search before the stats command. In this example, after the search results are organized into bins, the stats command returns the average "thruput" of each "host" for every 5 minute time span. The search results are arranged by _time and host.
...| bin span=5m _time | stats avg(thruput) by _time, host
Syntax
The required syntax is in bold.
- bin
- [<bin-options>...]
- <field> [as <newfield>]
Required arguments
- field
- Syntax: <field>
- Description: Specify a field name.
Optional arguments
- bin-options
- Syntax: bins | minspan | span | <start-end> | aligntime
- Description: Discretization options. See the Bin options section for the syntax and description for each of these options.
- newfield
- Syntax: AS <string>
- Description: A new name for the field.
Bin options
- bins
- Syntax: bins=<int>
- Description: Sets the maximum number of bins to discretize into.
- minspan
- Syntax: minspan=<span-length>
- Description: Specifies the smallest span granularity to use to automatically infer the span from the data time range.
- span
- Syntax: span = <span-length> | <log-span>
- Description: Sets the size of each bin, using a span length based on time or log-based span.
- <start-end>
- Syntax: start=<num> | end=<num>
- Description: Sets the minimum and maximum extents for numerical bins. The data in the field is analyzed and the beginning and ending values are determined. The start and end arguments are used when a span value is not specified.
- You can use the start or end arguments only to expand the range, not to shorten the range. For example, if the field represents seconds the values are from 0-59. If you specify a span of 10, then the bins are calculated in increments of 10. The bins are 0-9, 10-19, 20-29, and so forth. If you do not specify a span, but specify end=1000, the bins are calculated based on the actual beginning value and 1000 as the end value.
- If you set
end=10and the values are >10, theendargument has no effect.
- aligntime
- Syntax: aligntime=(earliest | latest | <time-specifier>)
- Description: Align the bin times to something other than base UTC time (epoch 0). The
aligntimeoption is valid only when doing a time-based discretization. Ignored ifspanis in days, months, or years.
Span options
- log-span
- Syntax: [<num>]log[<num>]
- Description: Sets to logarithm-based span. The first number is a coefficient. The second number is the base. If the first number is supplied, it must be a real number >= 1.0 and < the base number. Base, if supplied, must be real number > 1.0 (strictly greater than 1).
- Example: span=2log10
- span-length
- Syntax: <int>[<timescale>]
- Description: A span of each bin. If discretizing based on the
_timefield or used with a timescale, this is treated as a time range. If not, this is an absolute bin length.
- timescale
- Syntax: <sec> | <min> | <hr> | <day> | <month> | <subseconds>
- Description: Time scale units. If discretizing based on the
_timefield. - Default: sec
| Time scale | Syntax | Description |
|---|---|---|
| <sec> | sec | secs | second | seconds | Time scale in seconds. |
| <min> | min | mins | minute | minutes | Time scale in minutes. |
| <hr> | hr | hrs | hour | Time scale in hours. |
| <day> | day | days | Time scale in days. |
| <month> | month | months | Time scale in months. |
| <subseconds> | ms | cs | ds | Time scale in microseconds (us), milliseconds (ms), centiseconds (cs), or deciseconds (ds). |
Usage
The following sections contain information to help you understand and use the SPL2 bin command.
Differences between SPL and SPL2
The differences between the SPL and SPL2 bin command are described in this section.
Command options must be specified before command arguments
| Version | Example |
|---|---|
| SPL | ...bin myfield span=1d AS mytime |
| SPL2 | ...bin span=1d myfield AS mytime |
See also
- bin command
- bin command examples
| SPL2 Command Quick Reference | bin command examples |
This documentation applies to the following versions of Splunk® Cloud Services: current
Download manual
Feedback submitted, thanks!