Splunk Cloud

Search Reference

Download manual as PDF

Download topic as PDF

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

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. The int is not required. If <int> is not specified, 1 is assumed. For example if day 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 and timewrap-span is set to week, the field names are latest_week, 1week_before, 2weeks_before, and so forth. If series=exact, use the time_format argument to specify a custom format for the series names.
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 specify time_format="week of %d/%m/%y", this format appears as week of 13/2/17 and week of 20/2/17. If you specify time_format=week of  %b %d, this format appears as week of Feb 13 and week 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.

Using the time_format argument

If the format you specify does not contain any time specifiers, then 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 the addtotals command.
  • Use the addtotals and eval 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

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the timewrap command.

Last modified on 21 February, 2020
PREVIOUS
timechart
  NEXT
top

This documentation applies to the following versions of Splunk Cloud: 7.0.11, 8.0.2001, 7.1.3, 7.1.6, 7.2.4, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.0.13


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters