Package org.acemq.workloads.cli

Class WorkloadFile

java.lang.Object
org.acemq.workloads.cli.WorkloadFile
public final class WorkloadFile extends Object
Reads a workload, or a suite of them, from YAML or JSON. 

 name: orders-peak
 broker: amqp://guest:${BROKER_PASSWORD}@localhost:5672

 topology:
   exchange: orders
   queue: orders.new
   routingKey: order.created

 publishers:
   threads: 4
   rate: 50000
   messageSize: 1024

 consumers:
   concurrency: 8
   prefetch: 100
   handlerTime: 1ms

 warmup: 10s
 runFor: 2m

 expect:
   throughputAtLeast: 45000
   p99Below: 50ms

Secrets do not belong in this file

A workload file is meant to be committed and reviewed — that is most of its value. So ${VAR} is substituted from the environment before parsing, and a password written literally is a password in your git history.

The broker can come from outside the file

broker is optional here, because --broker can supply it. A file that names no broker is the right shape for one that is committed and pointed at a different cluster each time it runs, and refusing it would make the flag able only to override. Missing from both is still an error: see withBroker(java.lang.String).

Unknown keys are refused

A misspelled prefech: 100 that is silently ignored produces a run with the default prefetch and a report that says nothing about it. The result looks completely normal and answers a different question from the one asked.

  • Method Details

    • read

      public static WorkloadFile read(Path path)
      Parameters:
      path - a .yaml, .yml or .json file
      Returns:
      the workloads in it

    • parseYaml

      public static WorkloadFile parseYaml(String yaml, Function<String,String> environment)
      Reads workload YAML that is already in memory, exactly as read(Path) reads a file.

      For a tool that edits the file before it exists on disk — the studio's load designer validates what it is about to write with this, so "valid" there means what it means to the command line, rather than to a second parser that agrees most of the time.

      Parameters:
      yaml - the workload file's text
      environment - how ${VAR} references are resolved
      Returns:
      the workloads in it
      Throws:
      ConfigException - with a reason somebody can act on, when the file is not valid

    • withRamp

      public WorkloadFile withRamp(String spec)
      Makes every workload in the file a ramp, from --ramp start=1000,step=10%,....

      The flag is the ramp: block written on one line, and goes through the same parser, so the two cannot disagree about what a setting means. Where the file already has a ramp the flag's settings win, key by key.

      Parameters:
      spec - comma-separated key=value pairs, or null to change nothing
      Returns:
      the same file, with ramps

    • workloads

      public List<Workload> workloads()
      Returns:
      the workloads, in file order

    • withBroker

      public WorkloadFile withBroker(String override)
      Settles which broker each workload runs against, the command line winning over the file.

      Where the broker comes from cannot be decided while the file is being parsed, because the flag is not in the file. Deciding it there anyway is the bug this method exists to remove: broker was required of the file, so a file written to be pointed at a broker — one committed to a repository that has no business naming somebody's staging cluster — was refused before the flag that supplies the broker was ever looked at. The flag documented as overriding the file could therefore only override, never supply, and in fact did neither: the command line read it and then ran the file's broker regardless.

      A suite gets the one override for every workload in it. That is the same reading as "overriding the file": the file's brokers are what is being replaced, and replacing some of them would leave a run that is half against one broker and half against another with nothing saying which half is which.

      Parameters:
      override - the --broker URL, or null when the command line did not say
      Returns:
      the same workloads, each with the broker it will run against
      Throws:
      ConfigException - if a workload is left without a broker from either source

    • brokerUrl

      public String brokerUrl(int index)
      Parameters:
      index - which workload
      Returns:
      the broker URL it runs against
      Throws:
      ConfigException - if neither the file nor withBroker(java.lang.String) supplied one

    • ramp

      public Ramp ramp(int index)
      Parameters:
      index - which workload
      Returns:
      the ramp to run it as, or null when it is a single run

    • size

      public int size()
      Returns:
      how many workloads this file holds

    • describe

      public String describe()
      Returns:
      the resolved configuration, for --dry-run