Command-line arguments

The simulator takes the following command-line arguments:

 Available command line format:
          -f <argument> : Path to file containing commands to
                          execute on startup (e.g. -f file1 -f file2).
          -e <argument> : String of commands to execute on startup
                          (e.g. -e "start").
          -l <argument> : File name of log file to write to (default
                          is "simulator.log")
          -h            : Prints help on available command line
                          options, then exits.

  All arguments are optional.
  Commands specified by -f and -e arguments are run in the order given.

Below are commands for setting up endpoints, loading scenario definitions, running a session manually, managing load generation, configuring logging, viewing simulator status, and bxref:#loading-data-sets-and-binding-tables-to-themdata sets and tables[loading data sets and binding tables to them].

Setting up endpoints

Warning All endpoints, both local and remote, require endpoint addresses.

Configure endpoint addresses

To configure endpoint addresses, use the set-endpoint-address command:

"set-endpoint-address": Sets a remote address for a given schema and role
    Usage: set-endpoint-address <endpoint-name> <address-string>
    Example: set-endpoint-address hlr_endpoint theAddress

Create local endpoints

To create local endpoints, use the create-local-endpoint command.

The -schemas option is useful when some of the available schemas associated with the protocol adaptor type are incompatible, for example if two CGIN schemas have clashing activity contexts. When -schemas is not specified, all the available schemas for the protocol adaptor type are loaded.

"create-local-endpoint": Creates (or re-creates) a local endpoint using the
        address of the given endpoint
    Usage: create-local-endpoint <endpoint-name> <protocol-adaptor-type>
        [-propsfile properties-file]
         -propsfile - Configuration properties for the endpoint
        [-schemas schema-a,schema-b,...,schema-n]
         -schemas - Comma separated list of schemas to enable for the endpoint
    Example: create-local-endpoint theSwitch cgin -propsfile

Pause console to wait for local endpoints

Warning Protocol adaptors often take some time before all connections become available.

Use the wait-until-operational command to pause the command console until all local endpoints become available:

"wait-until-operational": Pauses the command reading thread until the
        simulator is operational, i.e. until all required connections are
        established. Use this in scripts before invoking the start-generating
        or run-session commands
    Usage: wait-until-operational [<timeout-ms>]
    Example: wait-until-operational 30000

Loading scenario definitions

Create role bindings

Warning Before a scenario definition can be successfully loaded, the scenario’s roles must be bound to endpoints which are already configured in the simulator.

To create the bindings, use the bind-role command:

"bind-role": Binds a role name to an endpoint
    Usage: bind-role <role-name> <endpoint-name> [-dialog <dialog>] [-config
        -dialog - Dialog in which the binding should take effect
        -config - Named configuration in which the binding should take
    Example: bind-role hlr_role hlr_endpoint
Tip The bindings can optionally be stored under a named configuration, which can be referenced by the load-scenario command. (When no configuration name is specified, the simulator uses global configuration.

Load the scenario definition file

To load scenarios, use the load-scenario command, which takes the path to the scenario definition file:

"load-scenario": Loads a scenario definition from a given file
    Usage: load-scenario <scenario-file> [-config <config-name>]
            -config - The named configuration to use
    Example: load-scenario path/to/some-scenario.scen
Note When a scenario is loaded, the simulator resolves which roles are local (usually 1 role) and which roles are remote, and resolves which messages are outgoing and incoming. If the first message is outgoing, the scenario definition is initiating. If the first message is incoming, the scenario definition is receiving.

Set a preferred scenario definition

When testing a specific scenario definition, when multiple scenario definitions are loaded, to set a preferred scenario definition, use the set-preferred-scenario command:

"set-preferred-scenario": Sets the preferred scenario definition to use when
        matching incoming dialogs and when generating load, or sets a probability
        distribution to use for generating load. Probability functions are defined
        as a comma seperated list of scenario-name:probability pairs.
        Probabilities must sum to 1.
    Usage: set-preferred-scenario [<scenario-name>[:<probability>,]] - The scenario definition
        name, optionally followed by a probability. If no argument is given, the scenario preference is cleared
    Example: set-preferred-scenario MyScenario
             set-preferred-scenario MyScenario:0.6,OtherScenario:0.4

Some caveats exist with the probability function mode.

  • All generating scenarios must be unambiguous — so no possibility of two scenarios matching at any point.

    • Ambiguities in message sequences can be resolved by ensuring each scenario has distinct data values.

  • Probability functions only apply to load generation.

  • A minimum of one field must be unique. Subscriber identity fields are appropriate for use to disambiguate otherwise identical scenarios.

    • These values may be hardcoded, or drawn from tables.

Running a session manually

To run a single session, use the run-session command:

"run-session": Runs a single session, without affecting the rate of sessions
               made by the load generator
    Usage: run-session <scenario-name> - The scenario definition name
    Example: run-session MyScenario

(Control returns to the console once the session is ended.)

Warning If multiple scenario definitions are loaded, and the network traffic does not match the given scenario definition, then the simulator will try to simulate and match the other loaded scenario definitions. In other words, invoking run-session scenario-A may end up matching scenario-B.

Managing load generation

Note If an initiating scenario has been set using the set-preferred-scenario command, the load generator will generate sessions using that scenario. Otherwise it will round robin amongst all the loaded initiating scenario definitions.
Warning As with the run-session command, if multiple scenario definitions are loaded and the network traffic does not match the chosen scenario definition, then the simulator will try to simulate and match the other loaded scenario definitions.

Control session rate

To control the session rate, use the set-session-rate and ramp-up commands:

"set-session-rate": Sets the rate in sessions per second. Defaults to 1.
    Usage: set-session-rate <sessions-per-second>
        sessions-per-second - a positive number. (Note: can't be '0'. Use the
        'stop' command to stop generating sessions)
    Example: set-session-rate 33.3
"ramp-up": Ramps up the session rate from a given rate to another given rate,
        in a given period
    Usage: ramp-up <initial-sessions-per-second> <target-sessions-per-second>
        (Session rates must be positive numbers, and ramp-period-seconds must
        be a positive integer)
    Example: ramp-up 33.3 45 120

Start and stop load generation

To toggle the load generator on and off, use the start-generating and stop-generating commands:

"start-generating": Starts generating sessions
    Usage: start-generating (no args)
"stop-generating": Stops generating sessions
    Usage: stop-generating (no args)

Configuring logging

Note The Scenario Simulator handles logging using log4j. The log4j configuration file,, by default writes logging to logs/simulator.log.
Warning With the default configuration, if two scenario instances are running from the same directory, they will both write to the same log file. When running multiple instances of the simulator, use the -l <logfile> command line option to write to different log files. See the Starting and Stopping the Simulator page for details.
Tip The default configuration writes logging at INFO level or above. Setting the logging level to DEBUG can help troubleshoot problems.

Viewing simulator status

Warning The simulator does not write output to the console for each session, except for user-initiated sessions started using the run-session command.

To view the status of the simulator, either immediately or periodically, use the print-status command:

"print-status": Prints the current status of the simulator
    Usage: print-status [<interval-seconds>]
        interval-seconds - The number of seconds between each printing, or '0'
        to stop printing
        (If no args, prints the status once)
    Example: print-status 5

Resetting simulator statistics

To reset the simulator statistics, use the reset-stats command:

"reset-stats": Resets current simulator statistics
    Usage: reset-stats (no args)

Loading data sets and binding tables to them

To load external data sets (specified as CSV files) into the simulator, use the load-data-set command:

"load-data-set": Loads a data set in CSV format from the given file
    Usage: load-data-set <data-set-name> <csv-file-path>
    Example: load-data-set my-data-set path/to/my-data-set.csv

To bind tables in scenario definitions to data sets (similar to how roles bind to endpoints), use the bind-table command:

"bind-table": Binds a table name to a data set
    Usage: bind-table <table-name> <data-set-name> [- -config <config-name>]
        -config - Named configuration in which the binding should take
    Example: bind-table my-table my-data-set
Previous page Next page