Time

Payload timestamps should advance with simulated traffic, not with documentation rendering or connector delay. Time functions use the scenario event clock.

The result

The one-second generator interval advances now() while the fixed promised date stays unchanged:

{"createdAt":"2026-01-02T03:04:05Z","expiresAt":"2026-01-03T03:04:05Z","startedAt":"2026-01-02T02:34:05Z","day":"2026-01-02","displayTime":"2026-01-02T03:04:05Z","promisedDate":"2026-01-10"}
{"createdAt":"2026-01-02T03:04:06Z","expiresAt":"2026-01-03T03:04:06Z","startedAt":"2026-01-02T02:34:06Z","day":"2026-01-02","displayTime":"2026-01-02T03:04:06Z","promisedDate":"2026-01-10"}

Generate order times

defaults:
  seed: 42
  clock:
    start: 2026-01-02T03:04:05Z
generators:
  - name: orders
    config:
      interval: 1s
      maxEvents: 2
    value:
      createdAt: =now()
      expiresAt: =addDuration($createdAt, 24h)
      startedAt: =subtractDuration($createdAt, 30m)
      day: =now(format=yyyy-MM-dd)
      displayTime: =formatDateTime(now(), format=RFC3339)
      promisedDate: =dateBetween(2026-01-10, 2026-01-10)

With a fixed defaults.clock.start, timestamps are reproducible. Without one, a run starts its scenario clock from the current time.

now(format?, timezone?)

Returns the current scenario event time.

Bare now() returns a timestamp value, which JSON encodes in RFC 3339 form with up to nanosecond precision. Pass format to return a formatted string.

createdAt: =now()
day: =now(format=yyyy-MM-dd)
stamp: =now(format=RFC3339)
millis: =now(format=RFC3339Milli)
hourMinute: =now(format=yyyy-MM-dd:HH-mm)
localDay: =now(format=yyyy-MM-dd, timezone=UTC)

With defaults.clock.start: 2026-01-02T03:04:05Z:

{"createdAt":"2026-01-02T03:04:05Z","day":"2026-01-02","stamp":"2026-01-02T03:04:05Z","millis":"2026-01-02T03:04:05.000Z","hourMinute":"2026-01-02:03-04","localDay":"2026-01-02"}

Named layouts are RFC3339, RFC3339Milli, RFC3339Nano, RFC1123, and RFC1123Z. Pattern tokens include yyyy, MM, dd, HH, mm, ss, and SSS. timezone must be an IANA timezone and is only valid when format is present.

dateBetween(start, end)

Returns a yyyy-MM-dd string selected between two inclusive dates.

birthDate: =dateBetween(1970-01-01, 2000-12-31)

{"birthDate":"1970-05-29"}

end must be the same as or later than start.

dateTimeBetween(start, end)

Returns a UTC timestamp selected from the inclusive interval.

occurredAt: =dateTimeBetween(2026-01-01T00:00:00Z, 2026-01-02T00:00:00Z)

{"occurredAt":"2026-01-01T12:03:03.676623051Z"}

Both arguments must be date-time values, and end must not be earlier than start.

addDuration(timestamp, duration) and subtractDuration(timestamp, duration)

Shift a timestamp by a signed duration and return a UTC timestamp. A date-only input means midnight UTC. Durations may be literal strings or expressions such as randomDuration(1h, 24h). The scenario clock itself does not change.

expiresAt: =addDuration($createdAt, 24h)
startedAt: =subtractDuration($createdAt, 30m)
randomExpiry: =addDuration($createdAt, randomDuration(1h, 24h))

Invalid inputs and results outside JSON timestamp years 0 through 9999 fail.

formatDateTime(value, format, timezone?)

Formats an existing date-time value with the same patterns, layouts, and timezone rules as now.

day: =formatDateTime(now(), format=yyyy-MM-dd, timezone=UTC)
stamp: =formatDateTime($createdAt, format=RFC3339Milli)

With createdAt: =now() and defaults.clock.start: 2026-01-02T03:04:05Z:

{"day":"2026-01-02","stamp":"2026-01-02T03:04:05.000Z"}

Use now(format=...) when formatting the current event time directly. Use formatDateTime for a value from a field, variable, or another time function.

clockStart()

Returns the pinned scenario start time (or the wall time captured when the run began if defaults.clock.start was omitted). Unlike now(), it does not move when the generator paces forward.

origin: =clockStart()
seenAt: =now()

timestamp(start, advanceBy, …)

Builds a per-expression sequence that advances on its own cursor, independent of generator interval or rate. Use it for payload timelines denser than event pacing.

eventAt: =timestamp(start=2026-03-01T04:58:00Z, advanceBy=5m)

Windowed densification keeps a default gap and overrides matching cron minutes:

eventAt:
  =timestamp:
    start: 2026-03-01T04:58:00Z
    advanceBy:
      default: 5m
      windows:
        - when: "* 5 * * *"
          by: 1s

Repo demos: examples/functions/timestamp_sequence.yaml and examples/functions/timestamp_arithmetic.yaml.

Clock start and pacing are explained in Time and pace. For duration strings rather than timestamps, use randomDuration.

Next: format strings and read environment values.