As explained here, a Scenario is a hierarchical structure that contains at least 1 Task and each Task contains at least 1 Action. For each such element of a Scenario tree there is a corresponding Java class.

Defining a Scenario thus translates into constructing the Scenario tree by instantiating objects of those classes, setting at least their required properties, and wiring the objects together properly.

A simple Scenario can be constructed with a few lines of code:

Scenario scenario = new Scenario("ScenarioName");
Task task = scenario.addTask("TaskName");
Action action = task.addAction("ActionName");
action.setTool("MyTool");
action.setToolconfig(new File("etc/myTool.xml"));
action.addProxy("tp1");
action.produce("avg").configure("interval", 10);

The following sections explain what properties can be set for a Scenario, Task, and Action.

Creating a Scenario

Only a few properties can be set for a Scenario. The name, which is required, is set in the constructor. Optionally, a description and keywords can be set.

scenario.setDescription("Some description of the scenario");
scenario.addKeyword("Project XY");
scenario.addKeyword("LTE");

Creating a Task

The simplest way to construct a Task and attach it to a Scenario is:

Task task = scenario.addTask("TaskName");

For a Task, the name, description, and keyword properties are optional and can be defined via the respective setter methods.

Setting the name of a Task is strongly recommended as the Task name is used in many logging statements to indicate the origin of a message.

Defining the active period of a Task

By default, a Task starts when the Execution of its parent Scenario starts and ends when the Execution ends. This default behavior can be modified by configuring 2 parameters: deltaStart and duration.

The property deltaStart represents the number of seconds that the Task start is delayed w.r.t the parent Scenario. The duration defines the number of seconds until the Task stops.

task.setDeltaStart(10);  // 10 seconds after the start of the execution
task.setDuration(60);    // run for 1 minute

Creating an Action

To create an Action and attach it to a Task:

Action action = task.addAction("MyAction");

For any Action, at least the following properties have to be set:

• the MinerTool to use
• the configuration of the MinerTool
• where the MinerTool has to be employed.

Defining the MinerTool

action.setTool("MyTool");

The parameter is the name of the MinerTool which is provided in the documentation of the MinerTool.

Defining the MinerTool configuration

Three types of configuration sources can be utilized to define the MinerTool configuration: a String, a File or a Document:

• String:

  action.setToolconfig("<xml.../>");

• File:

  action.setToolconfig(new File("etc/config.xml"));

• Document:

  org.w3c.Document toolconfig = . . .
  action.setToolconfig(toolconfig);

Defining the ToolProxy (-ies)

An Action must be bound to at least 1 ToolProxy.

action.setProxy("proxyName");

The method returns a Proxy object which represents a ToolProxy. It can be used in subsequent setProxy() calls.

Proxy tp1 = action.setProxy("tp1");
action2.setProxy(tp1);

A Proxy object can also be instantiated directly.

Proxy tp2 = new Proxy("tp2");

As described in section “The Result class“, Proxy objects are used in the Result class to define at which ToolProxy a result was produced.

Defining multiple ToolProxies

Depending on the type of MinerTool, an Action may need to be active on multiple ToolProxies. As an example, the IPPMTool requires that the Action is bound to 2 ToolProxies: 1 ToolProxy acts as a traffic source, and the other one acts as a traffic sink.

action.addProxies("tp1", "tp2");

Alternatively, a user may want to run an Action on more than 1 ToolProxy even though the MinerTool only requires a single ToolProxy for execution. Note that this only makes sense if the same MinerTool configuration is valid and meaningful on all selected ToolProxies. As an example, assume that a MinerTool monitors performance parameters of a host (CPU load, free memory, etc.) and that the same configuration is valid for all Linux-based hosts. In that case, it is sufficient to define 1 Action and bind it to all the Linux-based ToolProxies.

String[] linuxProxies = {"linux1", "linux2", "linux3", "linux4"};
action.addProxies(linuxProxies);

Each result contains a reference to the ToolProxy where it was generated so that it is possible to distinguish the various results that are delivered by an Execution of the Scenario. Note that, as explained in section “Restricting queries”, it is possible to restrict the result retrieval to a subset of an Action’s ToolProxies, e.g. linux1 and linux4 in the above example.

To summarize, the minimum Action definition looks similar to the following code snippet:

Action action = task.addAction("ActionName");
action.setTool("MyTool");
action.setToolconfig(new File("etc/config.xml"));
action.addProxy("tp1");

Defining the requested results

The documentation of a MinerTool lists the result classes that the tool can possibly deliver. By default, none of them are generated! A user must actively define which result classes the MinerTool has to produce. This is achieved by calling the produce() method of an Action.

ResultHandle hlossRatio = action.produce("lossRatio");

In this case, the MinerTool that is employed in Action action is requested to produce the result class “lossRatio”. The return value is a ResultHandle object. It is used to further configure the result request as shown in the following subsections. During and/or after the Execution, the ResultHandle is used to retrieve results from the MINER Server as explained in section “Processing execution results“.

Configuring a result request

A result class offered by a MinerTool may have required and/or optional configuration parameters. As an example, let’s assume that the “lossRatio” result type has a required configuration parameter called interval that defines the length of the time interval over which the average is computed. This interval parameter is configured in the following way:

hlossRatio.configure("interval", 5);

Setting a result reporting interval

By default, a ToolProxy reports each result separately to the MINER Server. This behavior can be modified per MinerTool result class by setting a so called report interval. The parameter defines the number of results that must accumulate before the ToolProxy sends the accumulated results to the MINER Server.

hlossRatio.setReportInterval(10);

In this example, 10 instances of “lossRatio” need to accumulate before they are sent to the Server. When an Action finishes, any remaining results are (of course) sent – no matter how few there are.

Defining Conditions on a result class

On the basis of the requested result class it is possible to formulate a Condition that must be fulfilled. The semantic is that the Condition must be true at all times. If a Condition is violated, an alarm is generated by the ToolProxy and sent to the MINER Server where one or more notifier(s) will handle the alarm. The default notifier, which is always present, logs the alarm to the database so that it will be reported in the Executionlog.

A Condition is composed of 1..N Subconditions. It is the Subcondition that is associated directly with a ResultHandle. The Condition defines how these Subconditions are logically combined. The logicalOperator can be set to Condition.ALL or Condition.ANY. The meaning is the following:

logicalOperator	description
ALL	the Condition is fulfilled if all Subconditions are fulfilled
ANY	the Condition is fulfilled as long as at least 1 Subcondition is fulfilled

In case of Condition.ANY, the holdTime defines for how long a Subcondition is regarded as violated. More precisely, it is considered violated in the time interval [t0 ; t0 + holdTime] where t0 is the time when the violation occured.

Condition condition = action.addCondition(Condition.ANY);
condition.addSubcondition(hlossRatio, "<", 5);
condition.addSubcondition(hDelay, "<", 200);
condition.setHoldTime(5);

Defining a save pattern

As described in section “Saving results“, the Results class provides static utility functions to conveniently retrieve and save results in 1 step. Some of these methods automatically determine the result output file name.  The name of the output file can be influenced by defining a so called savePattern.

ResultHandle hlossRatio = action.produce("lossRatio");
hlossRatio.setSavePattern("ippm/.log");

Please see the section “Automatic naming of result files” for a description on how the savePattern is used to derive the output file directory and name.

Defining the active phase of an Action

By default, an Action starts when its parent Task starts and ends when its parent Task ends. There are two principal ways to alter this behavior:

• using time offsets
• using event-based activation / deactivation

Using time offsets to define the active phase of an Action

The property deltaStart represents the number of seconds that the Action start is delayed w.r.t the parent Task. The duration defines the number of seconds until the Action stops.

action.setDeltaStart(10);  // start 10 seconds later than the parent task
action.setDuration(60);    // run for 1 minute

Event-based activation / deactivation of an Action

Since clientlib version 3.0 it is possible to trigger the activation of an Action via an Event. In this case, the Action goes through its initialization phase in the same way as any Action does. However, when the Execution enters the active phase, this action remains inactive until the activation event is received. It this event doesn’t arrive until the end of the execution – which is perfectly fine – the action is never activated.

An Event is a simple Java class that is constructed from a name provided as a String.

Event event = new Event("someName");

To enable event-based activation of an Action, at least 1 activation Event must be defined for the Action. It possible to define multiple Events – in this case the Action becomes active when the first event arrives.

action.addActivationEvent(event);
action.addActivationEvent(event1, event2);     // Logical OR

The definition of deactivation events is analog.

action.addDeactivationEvent(event);
action.addDeactivationEvent(event1, event2);   // Logical OR

To send an Event to an active Execution, a simple

exec.sendEvent(event);

does the job. The ToolProxy will consequently activate / deactivate the Action(s) that depend on this event. It is possible to enrich the event object which (key,value) properties.

event.setProperty("key", "value");

A MinerTool has access to the event that triggered the (de-)activation as well as its properties.

Defining other optional Action properties

It is possible to set a name, description, and keywords for an Action.

action.setName("NTP");
action.setDescription("Periodically queries the NTP sync status of host X");
action.addKeyword("ntp");

Setting the name of an Action is strongly recommended as it is used in many logging statements to indicate the origin of a message.

Note that the name of an Action is often set at construction time.

Action action = task.addAction("NTP");

Scenario submission

When the Scenario specification is complete it must be submitted to the MINER Server.

scenario.submit();

The MINER Server strictly verifies the scenario specification. If the verification fails, some sort of MinerException is thrown. Otherwise, the Scenario is persisted in the database and can now be scheduled for immediate or later Execution.