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

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 --events 10 --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 --events across the whole scenario, not once per generator.

Flags

  • --events <count> — required; the maximum total preview events to print. The value must be greater than zero.
  • --seed <seed> — use this signed integer instead of defaults.seed. If neither is set, Synthtraffic generates a seed and reports it on stderr.
  • --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.

sample requires a valid license. See Install.

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