synthtraffic Get started
Docs menu

Getting started

Install Quickstart Overview

Build a scenario

Scenario file Generators vars and const Time and pace Defaults Relationships Schedules Instances Lifecycle Collections Connections Delivery behavior

Connectors

Kafka PostgreSQL HTTP File S3 GCS Azure Blob

Expressions

Syntax IDs and sequences Random Faker Selection Modifiers Math Logic Collections ref and previous Time functions Strings and env Easing

CLI

sample run studio

Studio

Overview Workspace and editor Sample and timeline Run and Stop

Reference

Diagnostics Faker data

CLI

run

Use run after a scenario is ready for real-time execution. It compiles one YAML or JSON file, honors pacing and delivery behavior, and either opens the configured destinations or writes the evaluated events to stdout.

Usage

synthtraffic run <scenario> [flags]

<scenario> is required and must be the path to one scenario file.

Run against configured destinations:

synthtraffic run scenario.yaml --seed 42

Keep every destination closed and inspect five evaluated events locally:

synthtraffic run scenario.yaml --stdout --events 5 --seed 42

Without --stdout, every emitted generator must route to a configured connection. Use sample or run --stdout for a value-only scenario.

Flags

  • --seed <seed> — use this signed integer instead of defaults.seed. If neither is set, Synthtraffic generates a seed and reports it on stderr.
  • --stdout — print evaluated payloads or destination-shaped envelopes instead of opening any configured destination.
  • --events <count> — stop after this many total emitted events. When provided, the value must be greater than zero.
  • --with-studio — open Synthstudio on the scenario’s parent folder and start Run there.
  • --port <port> — set the Studio listen port (default 8787). This flag is valid only with --with-studio.
  • -h, --help — show command help without running a scenario.

Output and delivery

With --stdout, value generators print payload JSON Lines. Kafka prints {topic, key, headers, value}. PostgreSQL prints {table, row}. HTTP prints a redacted {method, url, headers, body?} envelope. File and cloud storage print a redacted {prefix, value} envelope. No destination is contacted.

Without --stdout, generated data goes to the connections named by the generators. Run status, including the resolved seed and completion or failure details, is written to stderr rather than mixed with generated stdout data.

Stop conditions

The run stops when the scenario completes, the total --events cap is reached, Ctrl+C cancels it, or a runtime or destination error occurs. Scenario and generator maxEvents and maxDuration limits still apply. A lifecycle generator can finish earlier when all of its instances reach terminal states.

run requires a valid license. See Install.