Delivery behavior

An event can be generated correctly and still arrive late, go missing, or arrive more than once. Use delay, discard, and repeat to reproduce those delivery conditions.

These settings do not change the event payload or its scenario-clock timestamp. They change what is delivered after the event has been generated.

Delay a delivery

Suppose an order service must tolerate an event that arrives two seconds late:

config:
  delay:
    probability: 1
    duration: 2s

delay.probability is the chance of a delay, from 0 to 1. Probability 1 delays every event; 0.25 delays roughly one quarter. delay.duration is how long delivery waits.

The duration can also vary:

config:
  delay:
    probability: 0.25
    duration: =uniformDuration(100ms, 2s)

run waits until the release time. sample previews the same event immediately without sleeping.

Discard a delivery

A cart consumer may need to cope with missing updates. discard.probability is the chance that a generated event is not delivered:

config:
  discard:
    probability: 0.05

A discarded event still counts toward maxEvents because it was generated. It simply is not written to the destination.

By default, a discarded event is also unavailable to ref(). Set retainHistory: true when relationships should still be able to select it:

config:
  discard:
    probability: 0.05
    retainHistory: true

Repeat a delivery

An order notification consumer may receive duplicates. repeat.probability is the chance that an event receives extra deliveries:

config:
  repeat:
    probability: 0.1
    times: 2

repeat.times is the number of additional copies. When repetition is selected, times: 2 produces three deliveries in total: the original plus two identical copies.

Compare all three behaviors

The complete scenario uses one generator for each behavior. With seed 42, the observable result should be:

delayedOrders               1 generated, 1 delivered after 2s by run
lossyCartUpdates            4 generated, CART-00 and CART-02 delivered
repeatedOrderNotifications  2 generated, 4 delivered

Delayed, discarded, and repeated events

defaults:
  seed: 42

generators:
  - name: delayedOrders
    config:
      maxEvents: 1
      delay:
        probability: 1
        duration: 2s
    value:
      orderId: =seq(format=ORD-%02d)
      behavior: delayed

  - name: lossyCartUpdates
    config:
      maxEvents: 4
      discard:
        probability: 0.5
    value:
      cartUpdateId: =seq(format=CART-%02d)
      behavior: may-be-discarded

  - name: repeatedOrderNotifications
    config:
      maxEvents: 2
      repeat:
        probability: 1
        times: 1
    value:
      notificationId: =seq(format=NOTE-%02d)
      behavior: repeated-once

Press Try it. It previews seven delivered lines immediately: one delayed order, two surviving cart updates, and two identical copies of each notification. The same seed repeats the discard and repeat decisions.

When a generator combines delivery behaviors, Synthtraffic applies them in this order:

1. discard decides whether the event is delivered.
2. If the event is kept, repeat decides how many copies are delivered.
3. delay chooses the release time for each delivery.

Put these settings under defaults to share them across generators, or under one generator’s config to affect only that stream.

Run this file

Save the example as delivery-behavior.yaml. sample previews all decisions immediately; run waits for the configured two-second delay.

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 delivery-behavior.yaml --events 7 --seed 42

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

run generates for real destinations (Kafka, PostgreSQL, and so on). For a value-only file like this one — no connection yet — pass --stdout to print events locally instead of opening a destination.

synthtraffic run delivery-behavior.yaml --stdout --events 7 --seed 42

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

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

This completes the Build a scenario path. Next: publish the example to Kafka.