GCS

GCS uses the File artifact model: generators produce {prefix, value} envelopes, then the connection groups them into rolling JSON or JSONL objects.

The scenario below previews:

{
  "prefix": "orders/part-",
  "value": {
    "orderId": "ORD-001",
    "status": "placed"
  }
}

Write order objects

connections:
  objectStore:
    type: gcs
    bucket: synthtraffic-demo

generators:
  - name: orders
    connection: objectStore
    config:
      maxEvents: 2
    vars:
      orderId: =seq(format=ORD-%03d)
    prefix: orders/part-
    value:
      orderId: $orderId
      status: placed

bucket selects the destination. prefix becomes the beginning of each object name; it does not require a pre-existing folder.

Preview without GCS

sample prints a short preview to your terminal. It does not wait for real-time pacing, and it never opens Kafka, PostgreSQL, or other destinations.

synthtraffic sample gcs.yaml --events 2 --seed 42

docker run --rm \
  --env-file ./license.env \
  --volume "${PWD}/gcs.yaml:/work/gcs.yaml:ro" \
  synthtraffic/synthtraffic:latest \
  sample /work/gcs.yaml --events 2 --seed 42

run --stdout prints the destination-shaped envelope locally without opening the configured connection. Remove --stdout when you are ready to send to that destination.

synthtraffic run gcs.yaml --stdout --events 2 --seed 42

docker run --rm \
  --env-file ./license.env \
  --volume "${PWD}/gcs.yaml:/work/gcs.yaml:ro" \
  synthtraffic/synthtraffic:latest \
  run /work/gcs.yaml --stdout --events 2 --seed 42

Full flag lists: sample and run. Install and license: Install.

Neither command discovers credentials, opens a GCS client, or checks the bucket.

Connection settings

GCS connections do not accept region, endpoint, service-account-key, or path-style fields. concurrency must be a positive literal and limits simultaneous object commits.

Authentication

A connected run uses Google Application Default Credentials with read/write storage scope. Configure ADC in the environment where Synthtraffic runs—for example, with an attached workload identity or GOOGLE_APPLICATION_CREDENTIALS. Credential JSON is not a scenario field and should not be committed.

When running in Docker, the credential path must exist inside the container. Mount the credential file read-only and set GOOGLE_APPLICATION_CREDENTIALS to its container path, or use the platform’s workload identity.

Emulator use

There is no GCS endpoint key in the DSL. For local testing, the Google client honors the runtime environment variable STORAGE_EMULATOR_HOST. When it is set, Synthtraffic skips Application Default Credential discovery.

This distinction is intentional: the emulator host is process configuration, not scenario syntax.

Object and delivery behavior

• The bucket must already exist.
• Object names use {prefix}{runULID}-{ordinal}.{format}[.gz].
• Synthtraffic creates objects only when they do not already exist.
• jsonl objects use application/x-ndjson; json uses application/json. Gzip adds Content-Encoding: gzip.
• An event counts as delivered only after its artifact commits. Missing buckets, name collisions, credential failures, and upload failures fail the run.

Prefix validation, rolling thresholds, formats, compression, and stream eviction are identical to File.

Write for real

Configure ADC, create the bucket, and remove --stdout:

synthtraffic run gcs.yaml --events 2 --seed 42

Complete example: examples/connectors/gcs.yaml.