timewrap command: Overview, syntax, and usage
The SPL2 timewrap
command displays, or wraps, the output of the timechart
command so that every period of time is a different series.
Use the timewrap
command to compare data over specific time period, such as day-over-day or month-over-month. You can also use the timewrap
command to compare multiple time periods, such as a two week period over another two week period. See the Syntax section.
Use these links to quickly navigate to the main sections in this topic:
How the SPL2 timewrap command works
Because the SPL2 timewrap
command is used with the timechart
command, let's start with that.
The following search counts the number of earthquakes in Alaska where the magnitude is greater than or equal to 5.3. The results are organized in spans of 1 day.
|search source=all_month.csv place=*alaska* mag>=5.3 | timechart count() span=1d
The results look something like this:
_time | count |
---|---|
08 Sep 2024 | 1 |
09 Sep 2024 | 1 |
10 Sep 2024 | 1 |
11 Sep 2024 | 0 |
12 Sep 2024 | 0 |
13 Sep 2024 | 0 |
14 Sep 2024 | 1 |
15 Sep 2024 | 0 |
16 Sep 2024 | 0 |
The results continue through 2024-09-23 but are truncated in this example. |
Combining the timewrap and timechart commands
Now let's add the timewrap
command to the search and specify a <timewrap-span> of 1week
.
|search source=all_month.csv place=*alaska* mag>=5.3 | timechart count() span=1d | timewrap 1week
The results are organized based on the day you run the search, which in this example 02 Oct 2024. Going back in 1 week increments to the week that the data starts (08 Sep 2024), the results look something like this:
_time | 3weeks_before | 2weeks_before | 1week_before |
---|---|---|---|
26 Sep 2024 | 0 | 0 | |
27 Sep 2024 | 0 | 0 | |
28 Sep 2024 | 1 | 0 | |
29 Sep 2024 | 1 | 0 | 0 |
30 Sep 2024 | 1 | 0 | 1 |
01 Oct 2024 | 1 | 0 | |
02 Oct 2024 | 0 | 0 |
Using the <timewrap-span> argument
The <timewrap-span> you specify controls how many rows are returned in the results and the ranges for the counts displayed in the columns. The <timewrap-span> specified is 1week
so there are 7 rows in the output. Counting back from 02 Oct 2024, there are 3 weeks between 02 Oct 2024 and 08 Sep 2024, which is why the column headings refer to 3 weeks, 2 weeks, and 1 week before.
The first date in the output is 26 Sep 2024. Counting back 3 weeks is 05 Sep 2024. There are no events for that date, which is why the output contains no value in the column 3weeks_before
for 26 Sep 2024.
Look at the date 29 Sep 2024. Counting back 3 weeks is 08 Sep 2024. There is 1 earthquake for that date, as shown in the results for the first search.
This pattern continues for the rest of the results.
Syntax
- timewrap
- <timewrap-span>
- [align=now | end]
Required arguments
- <timewrap-span>
- Syntax: [<int>]<timescale>
- Description: A span of each bin, based on time. The
timescale
is required. Theint
is not required. If <int> is not specified, 1 is assumed. For example ifday
is specified for the timescale,1day
is assumed. See the Timescale options section.
Optional arguments
- align
- Syntax: align=now | end
- Description: Specifies if the wrapping should be aligned to the current time or the end time of the search.
- Default: end
Timescale options
- <timescale>
- Syntax: <sec> | <min> | <hr> | <day> | <week> | <month> | <quarter> | <year>
- Description: Time scale units.
Time scale Syntax Description <sec> s | sec | secs | second | seconds Time scale in seconds. <min> min | mins | minute | minutes Time scale in minutes. <hr> h | hr | hrs | hour | hours Time scale in hours. <day> d | day | days Time scale in days. <week> w | week | weeks Time scale in weeks. <month> m | mon | month | months Time scale in months.
Thetimewrap
command uses the abbreviationm
to refer to months. Other commands , such astimechart
andbin
use the abbreviationm
to refer to minutes.<quarter> qtr | quarter | quarters Time scale in quarters <year> y | yr | year | years Time scale in years.
Usage
You must use the timechart
command in the search before you use the timewrap
command.
The wrapping is based on the end time of the search. If you specify the time range of All time
, the wrapping is based on today's date. You see this in the timestamps for the _time
field and in the data series names.
Differences between SPL and SPL2
The following arguments from the SPL timewrap
command do not have an equivalent argument in the SPL2 timewrap
command.
- series
- time_format
See also
- timewrap command
- timewrap command: Examples
- Related information
- timechart command: Overview and syntax
timechart command: Examples | timewrap command: Examples |
This documentation applies to the following versions of Splunk® Cloud Services: current
Feedback submitted, thanks!