Generators

The Quickstart produced one kind of event. A marketplace needs several: products, customers, orders, and more. A generator describes one named stream, and a scenario can contain as many generators as the traffic needs.

Produce products and customers

We want one scenario to produce two different event shapes:

{"productId":"PROD-00","name":"Wireless headphones","stock":10}
{"customerId":"CUST-00","name":"Paul Considine"}

The generators list below contains one product stream and one customer stream.

Products and customers

generators:
  - name: products
    config:
      maxEvents: 2
    value:
      productId: =seq(format=PROD-%02d)
      name: Wireless headphones
      stock: =seq(start=10, step=5)

  - name: customers
    config:
      maxEvents: 2
    value:
      customerId: =seq(format=CUST-%02d)
      name: =faker(person.fullName)

Press Try it. Results are labelled products or customers, so you can see which generator produced each event.

Read one generator

The two generators in this example use three fields:

• name uniquely identifies the stream, such as products.
• config controls how that generator behaves. Here, maxEvents: 2 stops it after two events.
• value is the JSON shape emitted by that generator.

Inside value, the first character tells Synthtraffic how to treat a field:

• Plain values such as Wireless headphones are emitted exactly as written.
• Values beginning with =, such as =seq(...) and =faker(...), are expressions that Synthtraffic calculates.
• Values beginning with $ reuse a visible field or a value named under vars or const.

Expressions are function calls. They can use positional arguments, named arguments such as round=2, and modifiers such as optional, nullable, or unique. The Expressions reference lists every function and modifier when you need more detail.

Objects and arrays under value keep the nested shape you write.

One scenario, independent streams

These generators do not refer to each other, so they are independent. Synthtraffic takes turns between available generators while respecting each generator’s pace and limits.

When events are printed to a terminal, each generator’s value becomes one JSON line. The generator name is shown by Try it and Studio, but is not added to the JSON payload.

Run this file

Save the example as customers-and-products.yaml. --events 4 is a total command limit, not four events per generator. The scenario also allows only two products and two customers, so at most four events can be produced.

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 customers-and-products.yaml --events 4 --seed 42

docker run --rm \
  --env-file ./license.env \
  --volume "${PWD}/customers-and-products.yaml:/work/customers-and-products.yaml:ro" \
  synthtraffic/synthtraffic:latest \
  sample /work/customers-and-products.yaml --events 4 --seed 42

run generates for real destinations (Kafka, PostgreSQL, and so on). For a value-only file like this one — no connection yet — pass --stdout to print events locally instead of opening a destination.

synthtraffic run customers-and-products.yaml --stdout --events 4 --seed 42

docker run --rm \
  --env-file ./license.env \
  --volume "${PWD}/customers-and-products.yaml:/work/customers-and-products.yaml:ro" \
  synthtraffic/synthtraffic:latest \
  run /work/customers-and-products.yaml --stdout --events 4 --seed 42

Full flag lists: sample and run. Install and license: Install.

Next: reuse calculated values with vars and const.