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

Reference

Diagnostics

Synthtraffic diagnostics use stable ST codes so errors can be searched, tested, and documented without depending only on message text. Every validation error, warning, and many runtime failures include a code and a source location.

Diagnostic lines follow this shape:

file:line:column: severity STcode scenario.path: message

Example:

examples/connectors/kafka.yaml:16:5: error ST1312 generators[0].connection: unknown connection "kafk"

The first two digits identify the broad area:

  • ST11xx — defaults and compatibility notices
  • ST12xx — expression parsing and expression syntax
  • ST13xx — scenario validation, connections, generators, schedules, runtime config, Kafka, PostgreSQL, and HTTP rules
  • ST1400–ST1409 — HTTP routing templates and migration guidance
  • ST1410–ST1420 — storage connection, rolling, prefix, and output rules

Expressions

  • ST1203 — compact expression parsing failed
  • ST1210 — unsupported function name
  • ST1227 — unknown named time format
  • ST1228 — now(timezone=...) without format
  • ST1245 — easing / easingChain missing from, to, or over
  • ST1246 — invalid over (must be a positive event count or positive duration)
  • ST1247 — unknown easing curve
  • ST1248 — invalid easingChain block shape
  • ST1249 — easingChain mixes event-count and duration over values
  • ST1250 — unknown easingChain step field

Scenario, pace, and connections

  • ST1312 — a generator references a connection name that does not exist
  • ST1320–ST1324 — schedule stage/run / dependency ordering rules
  • ST1325 — invalid schedule.cycle requirements (missing stage/generator maxEvents, or non-positive stage maxEvents)
  • ST1330 — invalid rate
  • ST1331 — invalid maxEvents
  • ST1332 — invalid maxDuration
  • ST1375 — duration-only generation requires a finite rate or interval
  • ST1376 — rate and interval cannot both be set
  • ST1377 — invalid interval
  • ST1379 — invalid cron expression in rate.windows[].when
  • ST1380 — invalid rate object shape (default / windows)
  • ST1381 — invalid instances.startGap
  • ST1382 — invalid discard.probability
  • ST1383 — invalid repeat (probability / times)

Kafka

  • ST1384 — Kafka tls must be a boolean literal
  • ST1385 — Kafka sasl must be an object
  • ST1386 — Kafka sasl.mechanism must be plain, scram-sha-256, or scram-sha-512
  • ST1387 — Kafka sasl username/password must be a non-empty string or env()

HTTP

  • ST1390 — invalid HTTP generator output shape or missing HTTP connection
  • ST1391–ST1392 — missing or invalid HTTP baseUrl
  • ST1393 — unsupported HTTP method
  • ST1394–ST1395 — invalid HTTP timeout or concurrency
  • ST1396–ST1397 — invalid HTTP query object or non-scalar value
  • ST1398–ST1399 — invalid, duplicate, managed, or non-scalar HTTP header
  • ST1400 — missing or invalid HTTP generator path template
  • ST1401 — an old HTTP connection field must migrate to baseUrl or a generator request field

Storage

  • ST1410 — invalid storage connection or generator compatibility
  • ST1411 — missing or invalid storage root (directory, bucket, accountUrl, or container) or provider endpoint/region
  • ST1412–ST1415 — invalid storage format, compression, rolling policy, or open-stream limit
  • ST1417 — missing storage prefix or value, or a storage field used with the wrong connector
  • ST1418 — invalid storage prefix
  • ST1419 — two generators share one storage connection and literal prefix (warning)
  • ST1420 — the complete storage artifact name exceeds a portable provider or file-component limit

Notes

JSON Schema can catch many shape errors in editors, but compiler diagnostics are canonical because they include source locations, scenario paths, and semantic rules that JSON Schema cannot fully express.