LOG IN SIGN UP
Documentation

Date- and time-related VCL features

By default VCL includes the now variable, which provides the current time (for example, Wed, 17 Sep 2025 23:19:06 GMT). Fastly adds several new Varnish variables and functions that allow more flexibility when dealing with dates and times.

Variables

The following variables have been added:

Name Location Description
now all The current time in RFC 1123 format format.
now.sec all Like the now variable, but in seconds since the UNIX Epoch.
time.start all The time the request started, after TLS termination, using RFC 1123 format.
time.start.sec all The time the request started in seconds since the UNIX Epoch, after TLS termination.
time.start.msec all The time the request started in milliseconds since the UNIX Epoch, after TLS termination.
time.start.msec_frac all The time the request started in milliseconds since the last whole second, after TLS termination.
time.start.usec all The time the request started in microseconds since the UNIX Epoch, after TLS termination.
time.start.usec_frac all The time the request started in microseconds since the last whole second, after TLS termination.
time.end deliver, log The time the request ended, using RFC 1123 format. Also useful for strftime.
time.end.sec deliver, log The time the request ended in seconds since the UNIX Epoch.
time.end.msec deliver, log The time the request ended in milliseconds since the UNIX Epoch.
time.end.msec_frac deliver, log The time the request started in milliseconds since the last whole second.
time.end.usec deliver, log The time the request ended in microseconds since the UNIX Epoch.
time.end.usec_frac deliver, log The time the request started in microseconds since the last whole second.
time.elapsed deliver, log The time since the request start, using RFC 1123 format. Also useful for strftime.
time.elapsed.sec deliver, log The time since the request start in seconds.
time.elapsed.msec deliver, log The time since the request start in milliseconds.
time.elapsed.msec_frac deliver, log The time the request started in milliseconds since the last whole second.
time.elapsed.usec deliver, log The time since the request start in microseconds.
time.elapsed.usec_frac deliver, log The time the request started in microseconds since the last whole second
time.to_first_byte deliver, log The time interval since the request started up to the point before the vcl_deliver function ran. When used in a string context, an RTIME variable like this one will be formatted as a number in seconds with 3 decimal digits of precision. In vcl_deliver this interval will be very close to time.elapsed. In vcl_log, the difference between time.elapsed and time.to_first_byte will be the time that it took to send the response body.

Functions

The following functions have been added:

Name Description
time.hex_to_time(<divider>, <hextime>) Takes a hexadecimal string value, divides by divider and interprets the result as seconds since UNIX Epoch.
time.add(<time>, <offset>) Adds offset to time.
time.sub(<time>, <offset>) Subtracts offset from time.
time.is_after(<time1>, <time2>) Returns TRUE if time1 is after time2. (Normal timeflow and causality required.)
strftime(<format>, <time>) Formats a time to a string. This uses standard POSIX strftime formats.
std.time(<string_to_parse>, <fallback_value>) Converts a string to a time variable. The following string formats are supported: Sun, 06 Nov 1994 08:49:37 GMT, Sunday, 06-Nov-94 08:49:37 GMT, Sun Nov 6 08:49:37 1994, 784111777.00, 784111777. Useful because time variables are needed as arguments for functions like time.add and strftime.
std.integer2time(<seconds_since_epoch>) Converts an integer to a time variable. To use a string, use std.atoi.

Examples

The following examples illustrate how to use the variables and functions.

time.hex_to_time, time.add, and time.is_after

if (time.is_after(time.add(now, 10m), time.hex_to_time(1, "d0542d8"))) {
  ...
}

strftime

set resp.http.Now = strftime({"%Y-%m-%d %H:%M"}, now)

set resp.http.Start = strftime({"%a, %d %b %Y %T %z"}, time.start)

std.time and std.integer2time

set resp.http.X-Seconds-Since-Modified = strftime({"%s"}, time.sub(now, std.time(resp.http.Last-Modified, now)));

std.integer2time(std.atoi("1445445162"));

Comparison operators like > < >= <= == != do not work with std.time or std.integer2time. Instead, you can compare two times using something similar to this:

if (time.is_after(now, std.integer2time(std.atoi("1445445162")))) {
  # do something
}

Back to Top