timewrap
Description
Displays, or wraps, the output of the timechart
command so that every period of time is a different series.
You can 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 Timescale options.
Syntax
The required syntax is in bold.
- timewrap
- <timewrap-span>
- [align=now | end]
- [series=relative | exact | short]
- [time_format=<str>]
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 Timescale options.
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
- series
- Syntax: series=relative | exact | short
- Description: Specifies how the data series is named. If
series=relative
andtimewrap-span
is set to week, the field names arelatest_week
,1week_before
,2weeks_before
, and so forth. Ifseries=exact
, use thetime_format
argument to specify a custom format for the series names. Ifseries=short
, the field names are an abbreviated version of the field names used withseries=relative
. Withseries=short
, the field names are abbreviated to "s" followed by a number representing the period of time. For example, if timewrap-span is set to week, the field names are s0, s1, s2 and so forth. The field s0 represents the latest week. The field s1 represents 1 week before the latest week. - Default: relative
- time_format
- Syntax: time_format=<str>
- Description: Use with
series=exact
to specify a custom name for the series. The time_format is designed to be used with the time format variables. For example, if you specifytime_format="week of %d/%m/%y"
, this format appears asweek of 13/2/17
andweek of 20/2/17
. If you specifytime_format=week of %b %d
, this format appears asweek of Feb 13
andweek of Feb 20
. See the Usage section. - Default: None
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. <quarter> qtr | quarter | quarters Time scale in quarters <year> y | yr | year | years Time scale in years.
The timewrap
command uses the abbreviation m
to refer to months. Other commands , such as timechart
and bin
use the abbreviation m
to refer to minutes.
Usage
The timewrap
command is a reporting command.
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.
Field names with a timechart BY clause
If you use a BY clause in the timechart
command part of your search, the field names generated by the timewrap
command are appended to the field names generated with the BY clause. For example, suppose you have a search that includes BY categoryId
in the timechart
command and the results look something like this:
_time | ACCESSORIES | SPORTS | STRATEGY |
---|---|---|---|
2020-05-21 | 5 | 17 | 32 |
2020-05-22 | 62 | 22 | 127 |
2020-05-23 | 65 | 34 | 128 |
2020-05-24 | 5 | 17 | 32 |
2020-05-25 | 62 | 22 | 127 |
2020-05-26 | 65 | 34 | 128 |
When you add the timewrap command, such as | timewrap w series=short
, the series field names are appended to the category ID names from the timechart BY clause.
The output looks something like this:
_time | ACCESSORIES_s1 | SPORTS_s1 | STRATEGY_s1 | ACCESSORIES_s0 | SPORTS_s0 | STRATEGY_s0 |
---|---|---|---|---|---|---|
2020-05-21 | 5 | 17 | 32 | |||
2020-05-22 | 62 | 22 | 127 | |||
2020-05-23 | 65 | 34 | 128 | |||
2020-05-24 | 5 | 17 | 32 | |||
2020-05-25 | 62 | 22 | 127 | 17 | 54 | 39 |
2020-05-26 | 65 | 34 | 128 |
Using the time_format argument
If you do not include any time specifiers with the time_format
argument, all of the data series display the same name and are compressed into each other.
Examples
1. Compare week over week
Display a timechart that has a span of 1 day for each count in a week over week comparison table. Each table column, which is the series, is 1 week of time.
... | timechart count span=1d | timewrap 1week
2. Compare today, yesterday, and average for the week
To compare a few days with the weekly average, you need to calculate the daily totals, calculate the weekly average, and remove the days you don't want to use. For example:
...| timechart count span=1h
| timewrap d series=short
| addtotals s*
| eval 7dayavg=Total/7.0
| table _time, _span, s0, s1, 7dayavg
| rename s0 as now, s1 as yesterday
- Use the
timewrap
command to generate results over the last 7 days. - By using the
series=short
argument, field names are generated in the output which start with "s", making it easy to create totals using theaddtotals
command. - Use the
addtotals
andeval
commands to calculate the average over those 7 days. - The
table
command is used to cut out days 3-7 so that only today, yesterday, and the weekly average are returned. - The
rename
command is used to rename the fields.
The output looks something like this:
_time | now | yesterday | 7dayavg |
---|---|---|---|
2020-02-20 15:00 | 0 | 0 | 0.0 |
2020-02-20 16:00 | 0 | 0 | 0.29 |
2020-02-20 17:00 | 0 | 0 | 0.0 |
2020-02-20 18:00 | 0 | 0 | 0.0 |
2020-02-20 19:00 | 0 | 0 | 0.57 |
2020-02-20 20:00 | 0 | 0 | 0.0 |
2020-02-20 21:00 | 0 | 0 | 0.29 |
2020-02-20 22:00 | 0 | 0 | 1.1 |
3. Compare a day of the week to the same day of the previous weeks
You can compare a day of the week to the same day of the weeks by specifying a filter at the end of the search. For example, to compare Wednesdays your search would be like this:
...| timechart count span=1h
| timewrap w
| where strftime(_time, "%A") == "Wednesday"
The output looks something like this:
_time | 4weeks_before | 3weeks_before | 2weeks_before | 1week_before | latest_week |
---|---|---|---|---|---|
2020-02-19 00:00 | 0 | 1 | 4 | 0 | 1 |
2020-02-19 01:00 | 2 | 0 | 0 | 0 | 1 |
2020-02-19 02:00 | 3 | 5 | 7 | 2 | 0 |
2020-02-19 03:00 | 6 | 4 | 0 | 1 | 2 |
2020-02-19 04:00 | 9 | 0 | 4 | 0 | 0 |
2020-02-19 05:00 | 2 | 8 | 7 | 3 | 1 |
2020-02-19 06:00 | 4 | 2 | 7 | 0 | 1 |
2020-02-19 07:00 | 6 | 9 | 2 | 2 | 0 |
If you change the timechart span to 1d instead of 1h, your output will look like this:
_time | 4weeks_before | 3weeks_before | 2weeks_before | 1week_before | latest_week |
---|---|---|---|---|---|
2020-02-19 | 32 | 29 | 31 | 8 | 6 |
See also
timechart | tojson |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403, 9.2.2406 (latest FedRAMP release)
Feedback submitted, thanks!