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

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

---

The CLI

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

---

Metrics

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

name	kind	description
generator_events_sent_total	counter	The total number of events successfully written to the target system. Use this counter with Prometheus rate to calculate events/second.
generator_iteration_duration_seconds	histogram	Measures 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.