Skip to main content

​
Overview

Time ranges in Slung allow you to filter data to specific time windows. Ranges are optional and support both absolute timestamps and relative time expressions.

​
Syntax

Time ranges are specified as the fourth component of a query, enclosed in square brackets: 
OP:SERIES:[TAGS]:[start,end]
Both start and end can be:
  • Absolute timestamps (microseconds since Unix epoch)
  • The special keyword now
  • Relative time expressions (e.g., 1m, 2h, 3d)
Time ranges are automatically normalized, so the order of start and end doesn’t matter. [now,1m] is equivalent to [1m,now].

​
Absolute Timestamps

Provide Unix timestamps in microseconds: 
AVG:cpu.total:[region=us-west]:[1700000000,1700000100]
This queries data from timestamp 1700000000 to 1700000100 (microseconds).

​
The now Keyword

Use now to reference the current time: 
SUM:requests:[enabled]:[1700000000,now]
Queries from the specified timestamp up to the current moment.

​
Relative Time Expressions

Relative time expressions let you specify durations relative to now. The format is: 
<amount><unit>
Where <amount> is a positive integer and <unit> is one of the supported time units.

​
Supported Time Units

​
Seconds

  • s, sec, secs, second, seconds
  • 1 second = 1,000,000 microseconds
Examples: 
[10s,now]    # Last 10 seconds
[30 seconds,now]

​
Minutes

  • m, min, mins, minute, minutes
  • 1 minute = 60 seconds
Examples: 
[2m,now]     # Last 2 minutes
[5 minutes,now]
[1 minute,now]

​
Hours

  • h, hr, hrs, hour, hours
  • 1 hour = 60 minutes
Examples: 
[3h,now]     # Last 3 hours
[1 hour,now]

​
Days

  • d, day, days
  • 1 day = 24 hours
Examples: 
[4d,now]     # Last 4 days
[1 day,now]

​
Weeks

  • w, wk, wks, week, weeks
  • 1 week = 7 days
Examples: 
[5w,now]     # Last 5 weeks
[2 weeks,now]

​
Whitespace in Relative Times

Whitespace is flexible and optional: 
[1m,now]      # Valid
[1 m,now]     # Valid
[1  minute,now]  # Valid

​
Real-World Examples

​
Last Hour of CPU Data

AVG:cpu.total:[env=prod]:[1h,now]
Calculates average CPU usage in production over the last hour.

​
Last Week with Specific Tags

SUM:s1:[enabled]:[1m,now]
Sums data points from the last minute where the enabled tag is present.

​
Reversing Start and End

MIN:temperature:[sensor=outdoor]:[now,24h]
Finds the minimum temperature in the last 24 hours. The range is automatically normalized to [24h,now].

​
Custom Time Window

COUNT:errors:[service=api]:[2weeks,1week]
Counts errors between 2 weeks ago and 1 week ago.

​
Queries Without Time Ranges

Time ranges are optional. Omit the range to query all available data: 
SUM:s1:[enabled]
This query has no time constraint and processes all historical data with the enabled tag.

​
Implementation Details

​
Time Calculation

Relative times are calculated by:
  1. Converting the amount and unit to seconds
  2. Multiplying by 1,000,000 to get microseconds
  3. Subtracting from the current time (now)
Example:
  • 2m at now = 10,000,000,000 microseconds
  • Calculation: 10,000,000,000 - (2 * 60 * 1,000,000) = 9,880,000,000
  • Range: [9,880,000,000, 10,000,000,000]

​
Normalization

After parsing both start and end values, the range is normalized: 
const range_start = @min(start, end);
const range_end = @max(start, end);
This ensures start <= end regardless of input order.

​
Error Handling

Invalid time range syntax will return an error: 
AVG:series1:[x]:[1mo,now]  # Error: InvalidRange ("mo" is not a valid unit)
AVG:series1:[x]:1,2        # Error: InvalidRange (missing square brackets)

Query Syntax

Complete query DSL reference

Tags

Tag filtering syntax

Build docs developers (and LLMs) love

Get started for freeTalk to us