Scenario file

A Synthtraffic scenario is one YAML or JSON document. Most scenarios start with a generator and add other sections only when they are needed.

This page shows where the four top-level sections belong. The focused lessons that follow explain how each section behaves.

The four top-level sections

A complete scenario can contain:

• defaults — behavior shared by the whole scenario
• connections — destinations such as Kafka, PostgreSQL, HTTP, files, or cloud storage
• generators — named streams that create events
• schedule — optional stages that control when generators run

Only generators is required.

defaults:
connections:
generators:
schedule:

defaults

defaults shares settings across the scenario:

defaults:
  seed: 42
  maxEvents: 100

You can share pacing, limits, Faker locale, retained history, and delivery behavior here. Defaults explains the complete section.

connections

connections names the destinations available to generators:

connections:
  eventBus:
    type: kafka
    brokers: [localhost:9092]

Connections are optional while you are previewing values. Connections explains how generators select them, and the connector guides cover destination-specific settings.

generators

generators is a list of named event streams. This example is a complete runnable scenario:

generators:
  - name: products
    value:
      productId: =seq(format=PROD-%02d)
      name: Wireless headphones

It produces:

{"productId":"PROD-00","name":"Wireless headphones"}
{"productId":"PROD-01","name":"Wireless headphones"}

Most authoring happens inside a generator. The next lesson builds separate product and customer streams and explains how their values become events.

schedule

schedule controls which generators run together and which groups must finish first:

schedule:
  stages:
    - run: [customers]
    - run: [orders]

Without a schedule, Synthtraffic runs every available generator. Schedules explains ordered stages and repeating batches.

Add only what the scenario needs

Start with generators, name, and value. Add shared defaults, connections, or a schedule only when the traffic requires them. The remaining Build a scenario lessons introduce those capabilities one at a time.

Next: build your first named event streams with Generators.