Skip to main content


Cheat sheet

Use these commands when you need a bit of boilerplate to get up and running.

Docker commands

Container start

docker run --env-file license.env \
-v $(pwd)/your-config.json:/home/config.json \
shadowtraffic/shadowtraffic:latest \
--config /home/config.json \
--watch --sample 10 --stdout
  • license.env contains your license environment variables and values.
  • your-config.json is your ShadowTraffic config file.

Docker Compose example

image: shadowtraffic/shadowtraffic:latest
- .:/workspace
entrypoint: ["java", "-jar", "/home/shadowtraffic.jar"]
command: ["--config", "/workspace/your-config.json"]
- shadowtraffic/license.env


CLI switches

  -c, --config <file>         Path to configuration file
--config-base64 <text> Instead of a file, use this Base64 encoded configuration data
-s, --stdout Ignore original output targets and forward all generated data to standard out
--no-pretty Do not use a pretty printer with --stdout when generating data.
--sample <n> Samples the generated output
-w, --watch Keep running and restart generation on config file changes
-q, --quiet Do not print any status text other than generated data to the command line.
--seed <n> Initializes random generators with this seed, enabling repeatable runs.
-h, --help Display this information


Prometheus metrics

ShadowTraffic exposes metrics through Prometheus. Inside the container, curl http://localhost:9400 to see the metrics, and forward port 9400 to your host if you want to ingest or graph the metrics into your own observability platform.

All metrics use two labels - connection name, and output target. For example, if you're connection is to Kafka and it's named "kafka", and the topic you're writing to is named "clicks", you'll see a label ("kafka", "clicks").

Metric list

generator_events_sent_totalcounterThe total number of events successfully written to the target system. Use this counter with Prometheus rate to calculate events/second.
generator_iteration_duration_secondshistogramMeasures the duration it takes to generate a single event, excluding the time to write it to your target system. Use this to see how fast or slow the data creation part of your ShadowTraffic configuration is.

All standard JVM metrics are also sent through Prometheus's JvmMetrics reporter.