synthtraffic Get started
Docs menu

Getting started

Install Quickstart Overview Synthtraffic MCP

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

sample

Use sample while building a scenario. It compiles one YAML or JSON file and prints a small, deterministic preview without opening a destination.

Usage

synthtraffic sample <scenario> [--events <count>] [flags]

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

For example:

synthtraffic sample scenario.yaml --seed 42

What the command does

  • Compiles the complete scenario and prints diagnostics before generating anything.
  • Prints one JSON line per preview event. A value generator prints its payload; a destination-shaped generator prints its Kafka, PostgreSQL, HTTP, file, or cloud-storage envelope.
  • Never opens connections, resolves destination credentials, or writes files.
  • Does not wait for rate, interval, or delay; scenario time still advances as configured.
  • Applies the preview event cap across the whole scenario, including repeated records, not once per generator.
  • Writes completion and attempted/discarded/emitted/repeated/history statistics to stderr, leaving stdout as payload-only JSON Lines.

Flags

  • --events <count> — optional; the maximum total preview events to print (default 100). The value must be greater than zero.
  • --seed <seed> — use this signed integer instead of defaults.seed. If neither is set, Synthtraffic uses 42.
  • --with-studio — open Synthstudio on the scenario’s parent folder and run Sample there instead of writing JSON Lines to stdout.
  • --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.

Scenario limits still apply, so sample can finish before reaching --events. A lifecycle can also finish when all instances reach terminal states. With --with-studio, the timeline shows at most 200 events.

Use sample for a quick, bounded, unpaced preview. Use run --stdout to exercise real-time scheduling without opening configured destinations; Run has no default CLI event cap.

sample requires a valid license. See Install.

  • First preview: Quickstart
  • Real-time execution and destinations: run
  • Scenario limits, clock, and seed: Defaults