v3.6 Scenarios

Contents

1. Introduction
   1.1. Old JSON Syntax
   1.2. JSR-223 Compliance
   
2. DSL
   2.1. Step
   2.1.1. Methods
   2.1.2. Types
   2.1.2.1. Basic
   2.1.2.2. Additional Shortcuts
   2.1.2.2.1. Built-In
   2.1.2.2.2. Custom
   2.2. Values Substitution
   
3. Examples
   3.1. Javascript
   3.1.1. External Command
   3.1.2. Load
   3.1.3. Parallel
   3.1.4. Weighted Load
   3.1.5. Chain Load
   3.2. Other Scripting Languages

1. Introduction

1.1. Old JSON Syntax

Old JSON scenarios will be still working as far as JSON scenario engine is wrapped into the JSR-223 compliant module and included. However, it's not recommended to use for the new scenarios as far as the support is dropped (no extensions will be available, previously existing bugs won't be fixed). For the JSON syntax please refer to the old version documentation.

1.2. JSR-223 Compliance

The new JSR-223 compliant scenario engines support has the following benefits in comparison to the old approach:

• The full power of scripting language including conditions, arithmetic, variables, etc
• Ability to customize and reuse the load steps
• Less complicated support (most of the logic and complexity goes to the 3rd party scripting engine which is much more stable and established)

2. DSL

Generally, to define a scenario an user should:

1. Define at least one step in the script
2. Invoke the defined steps using method run()

Notes:

1. Javascript scenarios are supported out-of-the-box (the corresponding engine is included in the JVM by default). So the examples below are in Javascript. It's necessary to put the custom JSR-223 implementation jar to the ext directory to use other scripting languages for scenarios.
2. Contrary to the JSON scenarios, new scenarios doesn't provide the configuration inheritance capability. Each scenario step should be configured independently. Shortcuts capability should be used instead of configuration inheritance for the new scenarios.

2.1. Step

The step is the basic entity which should be used to make a scenario. Mongoose's DSL defines few basic steps and a lot of additional shortcut steps.

2.1.1. Methods

1. config(configValuesMap)

   Appends the configuration structure element to the configurable step. An argument should be a dictionary/map with a structure equivalent to the configuration structure (see <MONGOOSE_DIR>/config/defaults.json file for the reference). Subsequent calls on the same step appends the configuration structure to the list. Any step implementation not supporting multiple configuration elements merges the list of the configurations (see the details). Returns the new step instance of the same type so the call may be included into the call chain.

2. step(childStep)

   Appends the child step to the composite step. The children steps are executed in the same order as they appended. Returns the new step instance of the same type so the call may be included into the call chain.

3. value(x)

   Sets the value to the step. The value meaning depends on the particular step implementation. Accepts single string value as argument. Subsequent calls on the same step discards previous value setting. Returns the new step instance of the same type so the call may be included into the call chain.

4. run()

   Executes the step and returns nothing. Should be invoked after all other step's methods (also terminate the call chain on the step if any).

2.1.2. Types

2.1.2.1. Basic

Step Type Name	Description	Methods	Example
Command	Execute an external shell command	config, value, run	link
Parallel	Execute the children steps in a parallel	step, run	link
Load	Execute a load	config, run	link
ChainLoad	Execute a chain load	config, run	link
WeightedLoad	Execute a weighted load	config, run	link

2.1.2.2. Additional Shortcuts

2.1.2.2.1. Built-In

1. PreconditionLoad

   The same as load but with disabled metrics output.

2. NoopLoad

   A load with noop operations type.

3. CreateLoad

   A load with create operations type.

4. ReadLoad

   A load with read operations type.

5. UpdateLoad

   A load with update operations type.

6. DeleteLoad

   A load with delete operations type.

7. ReadVerifyLoad

   A load with read operations type and enabled content verification.

8. ReadRandomRangeLoad

   A load with read operations type. Performs the reading of a single random byte range per operation.

9. ReadVerifyRandomRangeLoad

   A load with read operations type. Performs the reading of a single random byte range per operation. The data being read is verified also.

10. UpdateRandomRangeLoad

    A load with read operations type. Performs the single byte range update operations.

2.1.2.2.2. Custom

It's possible to define a custom shortcut step types what is especially useful for the load step type and its derivatives. This is because the load step supports only single configuration element so configuring multiple configuration elements lead to merging them into the single. The additivity rule works for the new configuration parameters (not set before). If the same configuration parameter is set again in the subsequent config call its value will be overridden.

Javascript example:

var CopyLoadUsingEnvVars = CreateLoad
    .config(
        {
            "item": {
                "input": {
                    "file": ITEM_INPUT_FILE,
                    "path": ITEM_INPUT_PATH
                },
                "output": {
                    "path": ITEM_OUTPUT_PATH
                }
            }
        }
    );

CopyLoadUsingEnvVars.run();

The example applies the additional configuration to the create_load step (which is derivativeof the load step) making the new copy_load step. The scenario uses the following environment variables: ITEM_INPUT_FILE, ITEM_INPUT_PATH, ITEM_OUTPUT_PATH. To perform a copy load step its necessary to supply only one valid items input, e.g. specify ITEM_INPUT_FILE value either ITEM_INPUT_PATH. The ITEM_OUTPUT_PATH value specifies the destination path for the items being copied.

To use the scenario above to copy the items using the items input file the following command may be issued:

export ITEM_INPUT_FILE=items2copy.csv
export ITEM_OUTPUT_PATH=/destination_path_bucket_container_etc
java -jar <MONGOOSE_DIR>/mongoose.jar \
    --test-scenario-file=copy.js

Otherwise, to use the scenario above to copy the items using the items input path (copy from the source path/bucket/container/etc to the target one):

export ITEM_INPUT_PATH=/source_path_bucket_container_etc
export ITEM_OUTPUT_PATH=/target_path_bucket_container_etc
java -jar <MONGOOSE_DIR>/mongoose.jar \
    --test-scenario-file=copy.js

2.2. Values Substitution

The environment variables are accessible from a scenario with the same name:

export ZONE1_ADDRS=127.0.0.1
export ZONE2_ADDRS=192.168.1.136
java -jar mongoose-next/mongoose.jar \
    --test-scenario-file=scenario/jsr223/js/chain_with_delay.js

The Javascript example scenario which uses these environment variables:

var config1 = {
    "item" : {
        "output" : {
            "delay" : "1m",
            "path" : "/default"
        }
    },
    "storage" : {
        "net" : {
            "node" : {
                "addrs" : ZONE1_ADDRS
            }
        }
    }
};

var config2 = {
    "load" : {
        "type" : "read"
    },
    "storage" : {
        "net" : {
            "node" : {
                "addrs" : ZONE2_ADDRS
            }
        }
    }
};

ChainLoad
    .config(config1)
    .config(config2)
    .run();

3. Examples

The complete set of the example scenarios is available in the <MONGOOSE_DIR>/example/scenario directory. The scenarios are sorted by the language.

3.1. Javascript

Javascript is the default scripting language which should be used for the custom user scenarios. Other scripting languages are not supported. An user may use deprecated JSON scenarios either JSR-223 compliant scripting language at his/her own risk.

3.1.1. External Command

Example:

Command
    .value("echo Hello world!")
    .run();

Note: The command is invoked using /bin/sh -c <CMD> command in order to support additional Unix shell capabilities like the pipeline. This allows to run the complex commands like ps alx | grep java but is not portable.

3.1.2. Load

Example:

Load.run();

3.1.3. Parallel

Example:

Parallel
    .step(step1)
    .step(step2)
    .run();

3.1.4. Weighted Load

See also the Weighted Load specification.

Example:

WeightedLoad
    .config(
        {
            "test" : {
                "step" : {
                    "limit" : {
                        "time" : "5m"
                    }
                }
            },
            "load" : {
                "generator" : {
                    "weight" : 20
                },
                "type" : "create"
            }
        }
    )
    .config(
        {
            "load" : {
                "generator" : {
                    "recycle" : {
                        "enabled" : true
                    },
                    "weight" : 80
                },
                "type" : "read"
            }
        }
    )
    .run();

3.1.5. Chain Load

See also the Chain Load specification.

Example:

var createConfig = {
    "test" : {
        "step" : {
            "limit" : {
                "time" : "1h"
            }
        }
    }
};

var readConfig = {
    "load" : {
        "type" : "read"
    }
};

var deleteConfig = {
    "item" : {
        "output" : {
            "file" : "items_passed_through_create_read_delete_chain.csv"
        }
    },
    "load" : {
        "type" : "delete"
    }
};

ChainLoad
    .config(createConfig)
    .config(readConfig)
    .config(deleteConfig)
    .run();

The example using the delay between different operations capability:

var config1 = {
    "item" : {
        "output" : {
            "delay" : "1m",
            "path" : "/default"
        }
    },
    "storage" : {
        "net" : {
            "node" : {
                "addrs" : ZONE1_ADDRS
            }
        }
    }
};

var config2 = {
    "load" : {
        "type" : "read"
    },
    "storage" : {
        "net" : {
            "node" : {
                "addrs" : ZONE2_ADDRS
            }
        }
    }
};

ChainLoad
    .config(config1)
    .config(config2)
    .run();

Note the environment variables ZONE1_ADDRS and ZONE2_ADDRS which should be set externally.

3.2. Other Scripting Languages

It's possible to use other JSR-223 compliant scripting language to write down custom scripts. However there's no official support for other scripting languages. The are example dockerfiles for the Groovy support and for the Jython support are available for the reference.