Instances

Sometimes you need repeated updates from the same orders, devices, or users—not a new identity for every event. Instances create that small, stable population inside one generator.

Three orders, two updates each

This generator has three instances and may produce six events. We want the ids to repeat in this order:

ORD-00  ORD-01  ORD-02  ORD-00  ORD-01  ORD-02

Stable order identities

generators:
  - name: orders
    config:
      maxEvents: 6
    instances:
      count: 3
      fields:
        orderId: =seq(format=ORD-%02d)
    value:
      orderId: $orderId
      updateNumber: =seq()
      status: processing

Press Try it. The generator takes turns across the three orders, then returns to the first. updateNumber changes on every event, but each orderId stays attached to its instance.

Fields that stay and fields that change

The location of a field determines when it is calculated:

• instances.count: 3 creates the stable population.
• instances.fields is calculated once for each instance. Use it for stable values such as an id, account type, or device model.
• value is calculated for every event. Use it for changing values such as a reading, balance, or timestamp.
• Copy an instance field into the output with $fieldName, as this example does with $orderId.

The generator’s rate or interval is shared by the whole population. It does not give every instance a separate event rate.

Bring instances online gradually

By default, every instance is available at the scenario clock’s start. Add startGap to stagger their activation:

instances:
  count: 3
  startGap: 500ms
  fields:
    sensorId: =seq(format=SENSOR-%02d)

The first sensor is available immediately, the second after 500ms, and the third after 1s of scenario time. An instance’s fields are calculated when that instance becomes active.

Use instances when multiple events belong to the same identity. Use a collection later when one event contains a nested list, such as an order with several line items.

Run this file

Save the example as order-instances.yaml.

sample prints a short preview to your terminal. It does not wait for real-time pacing, and it never opens Kafka, PostgreSQL, or other destinations.

synthtraffic sample order-instances.yaml --events 6 --seed 42

docker run --rm \
  --env-file ./license.env \
  --volume "${PWD}/order-instances.yaml:/work/order-instances.yaml:ro" \
  synthtraffic/synthtraffic:latest \
  sample /work/order-instances.yaml --events 6 --seed 42

Next: move each instance through a lifecycle.