Time and pace

A cart service may reject events with impossible timestamps or behave differently under a burst of traffic. Synthtraffic gives every scenario its own clock so generated timestamps and traffic pace stay aligned.

The result we want

We want three cart events separated by exactly 500ms:

{"cartId":"CART-00","product":"Wireless headphones","addedAt":"2026-03-01T09:00:00.000Z"}
{"cartId":"CART-01","product":"Wireless headphones","addedAt":"2026-03-01T09:00:00.500Z"}
{"cartId":"CART-02","product":"Wireless headphones","addedAt":"2026-03-01T09:00:01.000Z"}

Watch scenario time move

Three timestamped cart events

defaults:
  clock:
    start: 2026-03-01T09:00:00Z

generators:
  - name: carts
    config:
      interval: 500ms
      maxEvents: 3
    value:
      cartId: =seq(format=CART-%02d)
      product: Wireless headphones
      addedAt: =now(format=RFC3339Milli)

Press Try it. The output should match the three timestamps above.

The example introduces three time settings:

• clock.start fixes the scenario clock’s first timestamp.
• interval: 500ms moves that clock forward between cart events.
• =now(format=RFC3339Milli) reads the current scenario time into addedAt.

If you omit clock.start, the scenario clock begins when the command starts. The next lesson explains why clock settings live under defaults.

Choose rate or interval

Use one pacing style per generator:

• rate: 10/s — generate ten events per second
• interval: 500ms — leave a 500 millisecond gap between events

Put pace under a generator’s config. The next lesson shows how to share the same pace across generators. Do not set both a finite rate and an interval for one generator.

Fixed versus calculated intervals

A plain duration is fixed:

config:
  interval: 500ms

Every gap is exactly 500 milliseconds.

A value beginning with = is an expression:

config:
  interval: =uniformDuration(100ms, 500ms)

uniformDuration calculates a new gap between 100 and 500 milliseconds for each event. For example, consecutive gaps could be 180ms, 420ms, then 275ms. The same seed repeats the same sequence of calculated gaps.

Change rate on a clock schedule

A scalar rate stays constant. To change throughput against scenario time, use a default rate plus cron windows. The first matching 5-field cron wins:

defaults:
  clock:
    start: 2026-03-01T08:59:59Z
generators:
  - name: carts
    config:
      rate:
        default: 1/s
        windows:
          - when: "0 9 * * *"
            rate: 5/s

The first cart uses the default one-per-second gap. At 09:00 the window matches, so the next gap is 200ms:

08:59:59.000  →  09:00:00.000  →  09:00:00.200

Do not combine a windowed rate with interval. sample still does not wait between events; run honors the selected rate in real time. Invalid windows produce diagnostics such as ST1379.

Choose when to stop

Pace controls how quickly events are generated. Limits control when generation ends:

• maxEvents: 100 stops after 100 events.
• maxDuration: 30s stops after 30 seconds.

You can use either limit or both. If both are present, generation stops when the first limit is reached.

When maxDuration is used without maxEvents, set a finite rate or an interval. Otherwise an unlimited generator could produce events as fast as the machine allows for the whole duration.

Preview versus a real run

sample calculates the same event timestamps but does not wait between events. run follows the configured pace in real time.

Next: share settings and make runs repeatable with Defaults.