|
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.
|
Setting up endpoints
|
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
config/cgin.properties
Pause console to wait for local endpoints
|
|
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
Loading scenario definitions involves creating role bindings, loading the scenario definition file, and setting a preferred scenario definition.
Create role bindings
|
|
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
<config-name>]
-dialog - Dialog in which the binding should take effect
-config - Named configuration in which the binding should take
effect
Example: bind-role hlr_role hlr_endpoint
|
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
|
|
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.
|
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.)
|
|
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
|
|
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.
|
|
|
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.
|
Below are commands for controlling session rate and starting and stopping load generation.
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>
<ramp-period-seconds>
(Session rates must be positive numbers, and ramp-period-seconds must
be a positive integer)
Example: ramp-up 33.3 45 120
Configuring logging
|
|
The Scenario Simulator handles logging using log4j. The log4j configuration file, log4j.properties, by default writes logging to logs/simulator.log.
|
|
|
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.
|
|
|
The default configuration writes logging at INFO level or above. Setting the logging level to DEBUG can help troubleshoot problems.
|
Viewing simulator status
|
|
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
effect
Example: bind-table my-table my-data-set
