DCWoRMS Documentation and User Guide = Introduction = = DCWoRMS architecture = [[Image(arch.png, 820px)]]. = Input data = In general, input data in DCWoRMS consist of a single configuration file, description of workload and resources. Users may both generate new or read the existing synthetic data. Third party real workloads can also be imported by DCWoRMS. If any parameters are missing after importing a workload, they can be generated by DCWoRMS and added. == Configuration file == #ConfigurationFile The Experiment configuration file has typical, java resource bundle format. List of all available parameters and their interpretation is available below. * '''resdesc''' - path to file containing description of resources * '''readscenario.workloadfilename''' - path to workload file (in swf or gwf format) * '''readscenario.inputfolder''' - path to directory with xml job descriptions (optional) * '''createscenario.tasksdesc''' - path to xml file which describes detail workload generator configuration * '''createscenario.outputfolder''' - path to directory where all generated jobs will be placed * '''createscenario.workloadfilename''' - name of workload file in swf format which will be generated * '''createscenario.overwrite_files''' - determines if previously generated files should be overwritten. Two possible values of this field are: "true" and "false". * '''creatediagrams.gantt''' - determines if gantt chart should be generated. Two possible values of this field are: "true" and "false". * '''creatediagrams.tasks''' - determines if tasks execution times diagram should be generated. Two possible values of this field are: "true" and "false". * '''creatediagrams.taskswaitingtime''' - determines if tasks waiting time gantt diagram should be generated. Two possible values of this field are: "true" and "false". * '''creatediagrams.resutlization''' - determines if resource utlization chart should be generated. This files should contain the types of resources for which the diagram should be provided * '''creatediagrams.respowerusage''' - determines if resource power usage chart should be generated. This files should contain the types of resources for which the diagram should be provided Parameters from readscenario and createscenario groups should be used mutual exclusively. Path to this configuration file is the main argument of the DCWoRMS program. It should be used as follows: {{{ #!text/x-java java simulator.DataCenterWorkloadSimulator path/to/workload.properties }}} == Resource description == #ResourceDescription Resource description contains definition of resources both on physical (including data centers, containers, racks, nodes, processors, cores etc.) as well as on logical (scheduling entities) level. It is provided using an XML-based format. [https://apps.man.poznan.pl/svn/gssim/DCWoRMS/trunk/simulator/schemas/resources/DCWormsResSchema.xsd DCWormsResSchema.xsd] == Workload description == #WorkloadDescription Workload contains information about jobs, their structure, resource requirements, relationships, time intervals etc. We assumed a model in which each job consists of one or more tasks. A job may contain preceding constraints between tasks (workflow). The next sections provide information on how workloads are described and generated in DCWoRMS. The workload used to perform experiment consists of two parts: required swf/gwf format file and optional xml job description. Swf is the standard workload format, described by Dror Feitelson - see [http://www.cs.huji.ac.il/labs/parallel/workload/swf.html http://www.cs.huji.ac.il/labs/parallel/workload] for details. Xml job description format is described by following xsd schema [https://apps.man.poznan.pl/svn/gssim/DCWoRMS/trunk/simulator/schemas/grms3/GrmsJobDescriptionSchema.xsd GrmsJobDescriptionSchema.xsd] Better flexibility and expected functionality is achieved in DCWoRMS by introducing support of new swf header comments: '''!StartTime''' - defines moment in time when the simulation starts. If it is not provided, then "Thu Jan 01 01:00:00 CET 1970" is used. Example: {{{ ;StartTime: Mon Nov 03 10:00:00 CET 2008 }}} '''PUSpeed''' - defines processing unit speed. This value has no predefined unit. It is up to you how this field is interpreted, for example instruction per second or million of instructions per second. If it is not provided, then default value 1 is used. The value of PUSpeed is used to estimate task length expressed in instructions, which is calculated as multiply of PUSpeed value and Run Time and Number of Allocated Processors fields. Example: {{{ ;PUSpeed: 1 }}} '''IDMapping''' - this section allows you to join multiple jobs from swf file into single job with multiple tasks. IDMapping section consist of: * begin line: ;IDMapping: swfID:jobID:taskID * mapping between swf job id and new job and task id: ; id form swf file:new job id:task id * end line: ;IDMapping: end Example: Assume, that swf file contains two tasks with id 1 and 2. You can create new job, with two tasks by defining following mapping: {{{ ;IDMapping: swfID:jobID:taskID ; 1:4:10, 2:4:20 ;IDMapping: end }}} New job with id = 4 consisting of two tasks with id 10 and 20 will be created. The only constraint of IDMapping section is that swf jobs, which will become tasks in new job, must occur in swf one by one. No other jobs are allowed between these swf jobs which are mapped to tasks of one new job. The experiment can be executed with usage of single swf file or swf file with xml extension. If single swf is used, then task requirements like cpu count and requested memory are read directly from swf file. Notice, that information included in swf file is insufficient for using advance reservation in scheduling algorithm. To do so, you must provide xml extension of each job description and fill up its executionTime section. In xml files you can use any ids for job and tasks but you must provide correct IDMapping section (in swf file header) between xml job/task ids and swf job id. Otherwise, task start up parameters like submit time or task length in instructions will not be calculated correctly. If xml job description is used, then task requirements are read from xml description instead of swf file. === Workload generation === The main goal of workload design was to ensure, that all job descriptions which were used in real resource management system like GRMS or obtained from swf/gwf log can be used to perform experiment in DCWoRMS simulator. However, it my be difficult for all users to reach such workloads, therefore workload generator was created. Workload generator allows you to create any number of jobs and tasks, with sophisticated resource and time requirements. The result of generation process are: desired number of job descriptions in xml format and swf file with job descriptions and all necessary header parameters (see [https://apps.man.poznan.pl/svn/gssim/DCWoRMS/trunk/simulator/schemas/WorkloadSchema3g.xsd WorkloadSchema.xsd] for details). Configuration options are provided by two files: * *.properties file, which should provide values of all parameters from createscenario group and resdesc parameter (see [[#ConfigurationFile | configuration file]] for details) * xml configuration file, which is described by xsd schema [https://apps.man.poznan.pl/svn/gssim/DCWoRMS/trunk/simulator/schemas/WorkloadSchema3g.xsd WorkloadSchema.xsd] and contains configuration of random numbers generators, used to create job/task/workload parameters. Details about properties file are described above. Following part of this section describes all elements of xml configuration file. Main workload configuration elements: ==== '''!SimulationStartTime''' ==== Defines start time of the simulation in human readable form. The value should be provided in xsd time format. See [http://www.w3.org/TR/xmlschema-2/#dateTime www.w3.org] for details. Example: {{{ #!xml 2009-01-15T10:00:00 }}} ==== '''!JobCount''' ==== Defines number of jobs to be generated. This element is used as an alternative for . is element of type [[#RandParams | RandParams]]. Example shows how to create exactly 100 jobs: {{{ #!xml }}} ==== '''!SimulationTime''' ==== Defines length of the simulation. Generator will create number of jobs which can be executed in order during !SimulationTime. The value should be provided in xsd duration format. See [http://www.w3.org/TR/xmlschema-2/#duration www.w3.org] for details. This element is used as an alternative for . ==== '''!TaskCount''' ==== Defines number of tasks in each job. is element of type [[#RandParams | RandParams]]. Example shows how to configure generator to create minimum 1 and maximum 10 tasks in each job. The average number of tasks in job will be 5, with standard deviation 3.0 and normal distribution. {{{ #!xml }}} ==== '''!TaskLength''' ==== Defines length of the task in number of instructions. This value will be translated to the seconds with assumption that task of this length will be executed on a single and the slowest processor. The minimum speed of the processor is fixed as a minimum value of cpuspeed host parameters from resource description. The resource description file is specified by resdesc parameter in *.properties file. is element of type [[#RandParams | RandParams]]. Example shows how to configure generator to create task of minimum 500 and maximum 1500 instructions. The average length of all tasks will be 1000 instructions with standard deviation 500.0 and normal distribution. {{{ #!xml }}} The value of all fields in swf file expressed in seconds are calculated as division of task length in instructions and minimum speed of the single processor. If the minimum speed of the processor is 2, then the value of runtime field in swf file for task of length 764 instructions will be calculated as 764/2 = 382 seconds. ==== '''!JobPackageLength''' ==== Defines number of jobs which have the same submit time. Tasks which belongs to one job have always the same submit time. In swf file, submit time is interpreted as number of seconds after simulation start time. is element of type [[#RandParams | RandParams]]. ==== '''!JobInterval''' ==== Defines time space between submission of successive jobs. In other words, this is the difference between submission time of two successive jobs. The value is expressed in seconds. !JobInterval is element of type [[#RandParams | RandParams]]. ==== '''!ComputingResourceHostParameter''' ==== Defines generator which creates element in task resource requirements section. See [https://apps.man.poznan.pl/svn/gssim/DCWoRMS/trunk/simulator/schemas/grms3/GrmsJobDescriptionSchema.xsd GrmsJobDescriptionSchema.xsd] for detail description of task resource requirements. This element requires attribute named: ''metric''. The value of this attribute will be passed to task element as a value of its ''name'' attribute. The possible values of name attribute and thereby metric attribute are: osname, ostype, puarch, osversion, osrelease, memory, freememory, cpucount, freecpus, cpuspeed, application, diskspace, freediskspace, remoteSubmissionInterface, localResourceManager, hostname. In simulation values of cpucount and memory host parameters are used by default. Others are currently ignored. is element of type [[#RandParams | RandParams]]. ==== '''Preferences''' ==== This is the complex element, which was designed to describe section in task requirements. See [https://apps.man.poznan.pl/svn/gssim/DCWoRMS/trunk/simulator/schemas/grms3/GrmsJobDescriptionSchema.xsd GrmsJobDescriptionSchema.xsd] for detail description of task resource requirements. Element consist of list of elements. Each parameter must provide , , and elements. is optional. The values of these elements are passed to the attributes in parameter element in task resource requirements section. Name of the parameter elements and task parameter attributes are the same. Workload generated only for simulation purpose does not require section in task resource requirements, therefore element my be skipped in xml workload configuration. Importance and value are elements of type [[#RandParams | RandParams]]. ==== '''!ExecutionTime''' ==== This complex element was designed to describe section in task description. See [https://apps.man.poznan.pl/svn/gssim/DCWoRMS/trunk/simulator/schemas/grms3/GrmsJobDescriptionSchema.xsd GrmsJobDescriptionSchema.xsd] for details. consists of four child elements which have following interpretation: * - describes user expectation about how long the task is. It differs from prior element [[#TaskLength | ]] which defines real length of the task. Value of this element is interpreted as number of instructions, and it will be translated into the seconds in the same way as [[#TaskLength | ]] is. * - defines point in time from which task execution can be started. Value of this element is interpreted as number of seconds after [[#SimulationStartTime | ]]. * - defines point in time until task task execution must end. Value of this element is interpreted as number of seconds after [[#SimulationStartTime | ]]. It can be used as an alternative for . * - defines number of seconds after which task execution must end. This element can be used as an alternative for . , , and are elements of type [[#RandParams | RandParams]]. element is optional and it is not compulsory to use it in xml workload configuration. However, if advance reservation will be used, then and () are used as a begin and end time of the reservation. ==== '''!PrecedingConstraints''' ==== This element allows to create task workflow. Currently it is not supported in simulation process. ==== '''!RandParams''' ==== !RandParams represents set of attributes and elements which are used to configure random numbers generator and the way it is used. The attributes of !RandParams type can be divided into two groups: * '''defining statistics''' - following attributes are constraints which must be satisfied by the set of numbers created by generator: ''avg'' - average value, ''stdev'' - standard deviation, ''min'' - minimum value, ''max'' - maximum value, ''seed'' - number which initialize generator, ''distribution'' - generated set of numbers will have distribution determined by this attribute; possible values are: constant, normal, poisson, uniform, exponential, gamma, harmonic. * '''defining dependency''' - following attributes are used to define dependency between any elements in xml configuration file: ''id'' - element identifier, must be unique in entire file. Value of this attribute is required if value of containing element will be referenced by another element. ''refElementId'' - identifier of the element which is referenced by containing element. ''expr'' - defines dependency function. The x (independent variable) is pointed by the value of refElementId attribute. Defined expression may have any form acceptable by [http://www.beanshell.org/ BeanShell] interpreter. In general all mathematical operators like +, -, *, /, and brackets (, ) can be used. Example: {{{ #!xml }}} The order in which above values are resolved is following: cpucnt -> cpuspeed -> memory. Value for cpucnt will be calculated based on generator parameters. Value for cpuspeed will be calculated as a cpucnt generator result + 10; cpuspeed = cpucnt + 10 Value for memory will be calculated as a cpucnt generator result + 10 and multiply by 100; memory = (cpucnt + 10) * 100 Non linear functions can be also defined: {{{ #!xml }}} It is possible to join generator definition with dependency definition. In such case, value of the element is calculated according to the function from expr attribute. The result is then added to the value calculated by the random numbers generator. Example: {{{ #!xml }}} If cpucnt = 5, then cpuspeed = 32. Explanation: dependency expression returns 5 + 10 = 15, cpuspeed random numbers generator creates some value, for example 17, so the result is 15 + 17 = 32. In addition to above list of attributes, !RandParams type allows to define two child elements which can be used to define different configuration of generator for some time period or percentage of generated values. * '''!PeriodicValidValues''' - attributes of this element defines generator configuration. child element defines start time of period when this generator configuration is mandatory. child element defines end of this time period. For all time periods which are not covered by the time interval described by and , generator defined in involving element is mandatory. Example: {{{ #!xml 1970-01-01T01:10:00 1970-01-01T01:20:00 1970-01-01T01:30:00 1970-01-01T01:50:00 }}} Lets assume, that simulation starts at 1970-01-01T01:00:00 and ends at 1970-01-01T02:00:00. There are three different generator configurations, one in level and two on level. The interpretation of this configuration is as follows: the average execution duration for tasks which are submitted between 01:10:00 and 01:20:00 equals 10; the average execution duration for tasks which are submitted between 01:30:00 do 01:50:00 equals 20. Average execution durations for tasks which are submitted in any other time period ([01:00:00, 01:10:00], [01:20:00, 01:30:00], [01:50:00, 02:00:00]) equals 5. * '''!MultiDistribution''' - allows to define different generator configurations for some percentage of generated values. Example: {{{ #!xml 0.3 0.5 0.2 }}} Interpretation of above configuration is as follows: generator described by normal distribution is used for 30% of generated values, uniform for 50% and poisson for 20%. Percentage values can be interpreted as probability of usage this particular generator. It is not allowed to use generator configuration attributes (avg, min, max, etc) in involving element if !MultiDistribution is used. In such case, all values of elements must sum up to 1.0. = Scheduling concept = This section contains description of scheduling concept in DCWoRMS. Each scheduling plugin must implement the following interface. This interface provides queue management mechanisms for plugin developers. It consists of the following methods: * '' getName() '' * '' init() '' * '' getConfiguration() '' * '' schedule() '' choose which tasks should be moved to execution; may be invoked periodically (when TIMER event occurs). Frequency of TIMER event can be set by adding an element to the scheduling plugin definition in resource description file * '' placeTasksInQueues() '' is responsible for distributing tasks between queues. New tasks should be placed in queues, and after that, when declared event arrives, moved to execution. Input data for scheduling methods consists off: list of tasks in the system, queues, and available resources. In example section an implementation of !SchedulingPlugin is described in [#SchedulingPlugin Scheduling Plugin section] = Application performance modeling = DCWoRMS provides means to include specific application performance models during simulations. To this end, additional plugin and interface are included in the DCWoRMS framework. Implementation of this plugin allows researchers to introduce specific ways of calculating task execution time. Execution Time Estimation Plugin ''Input:'' task, allocated resources, completion percentage, event ''Output:'' estimated execution time of a task The following parameters can be applied to specify execution time of a task: * task length (number of CPU instructions) * task requirements * detailed description of allocated resources (processor type and parameters, available memory) * input data size * network parameters Based on these parameters an estimated execution time can be calculated in various ways depending on the specific applications and scenarios. = Simulation of energy efficiency = = Quick start = This section describes how to run an example experiment. [http://ant.apache.org/ Apache Ant] is required to compile DCWoRMS and run an experiment. * Prepare working directory (''working_dir'') in your local system and download DCWoRMS sources from [https://apps.man.poznan.pl/svn/gssim/DCWoRMS/]. The following command can be used to checkout DCWoRMS sources {{{ svn checkout https://apps.man.poznan.pl/svn/gssim/DCWoRMS/ }}} * The example experiments configurations are placed in ''working_dir/DCWoRMS/trunk/example'' directory. * Go to the main project directory ''working_dir/DCWoRMS/trunk'' and run Ant task: Parameters: run - ant target, it is responsible for compiling source code and starting experiment execution -Dconfig - path to *.properties file with experiment description {{{ bash$ ant run -Dconfig="example/experiment1/experiment1.properties" }}} Simulation is started by call of main method from //DataCenterWorkloadSimulator// class. Input parameter is an array of Strings. First String specifies the path to [[#ConfigurationFile | configuration file]]. For example: {{{ #!text/x-java String args[] = {"example/experiment1.properties"}; DataCenterWorkloadSimulator.main(args); }}} == Properties File == Example properties file: {{{ # Use single *.swf file as workload description. # Path to xml file which describes resource characteristics. resdesc=example/experiment1/resources1.xml # and swf file, which name is declared by readscenario.workloadfilename parameter. # Swf file must be placed in readscenario.inputfolder directory. readscenario.workloadfilename=example/experiment1/workload.swf # Choose directory where all result files should be placed. stats.outputfolder=../experiment1_result # Define the type and content of charts to generate # Gantt chart creatediagrams.gantt=true # Shows the execution times of tasks creatediagrams.tasks=true # Shows the waiting times of tasks creatediagrams.taskswaitingtime=true # Resource utilization chart - only for processors creatediagrams.resutilization=Processor }}} As we can see, it is necessary to specify resource description file. This file should be valid with [https://apps.man.poznan.pl/svn/gssim/DCWoRMS/trunk/simulator/schemas/resources/DCWormsResSchema.xsd DCWormsResSchema.xsd]. It should contain description of resources (e.g. number of processors, their speed, memory etc.). Furthermore, workload file is necessary to obtain information concerned with execution of simulation (e.g. execution of tasks). This workload file should be in the standard workload format (http://www.cs.huji.ac.il/labs/parallel/workload/swf.html) == Scheduling Plugin == #SchedulingPlugin === FCFS with Backfilling strategy local scheduling plugin=== {{{ #!text/x-java public class FCFSBF_LocalPlugin extends BaseLocalSchedulingPlugin { public SchedulingPlan schedule(SchedulingEvent event, TaskQueueList queues, JobRegistry jobRegistry, ResourceManager resManager, ModuleList modules) { SchedulingPlan plan = new SchedulingPlan(); // Chose the events types to serve. Different actions for different events are possible. switch (event.getType()) { case START_TASK_EXECUTION: case TASK_FINISHED: // our tasks are placed only in first queue (see BaseLocalPlugin.placeJobsInQueues() method) TaskQueue q = queues.get(0); // check all tasks in queue for (int i = 0; i < q.size(); i++) { TaskInterface task = q.get(i); // if status of the tasks in READY if (task.getStatus() == DCWormsTags.READY) { addToSchedulingPlan(plan, task); } } break; } return plan; } } }}} === FCFS with Backfilling strategy + DFS (Dynamic Frequency Scalling) local scheduling plugin=== {{{ #!text/x-java public class FCFSBF_DFSClusterPlugin extends BaseLocalSchedulingPlugin { public SchedulingPlanInterface schedule(SchedulingEvent event, TaskQueueList queues, JobRegistry jobRegistry, ResourceManager resManager, ModuleList modules) { ClusterResourceManager resourceManager = (ClusterResourceManager) resManager; SchedulingPlan plan = new SchedulingPlan(); // our tasks are placed only in first queue (see // BaseLocalSchedulingPlugin.placeJobsInQueues() method) TaskQueue q = queues.get(0); switch (event.getType()) { case START_TASK_EXECUTION: case TASK_FINISHED: // check all tasks in queue for (int i = 0; i < q.size(); i++) { TaskInterface task = q.get(i); // if status of the tasks in READY if (task.getStatus() == DCWormsTags.READY) { addToSchedulingPlan(plan, task); } } adjustFrequency(resourceManager.getProcessors()); } return plan; } // scale-up the frequency of allocated processors and scale-down the frequency of free ones private void adjustFrequency(List processors){ for(Processor cpu: processors){ if(cpu.getStatus() == ResourceStatus.FREE) { if(cpu.getPowerInterface().getSupportedPStates().containsKey("P3")) cpu.getPowerInterface().setPState("P3"); } else{ if(cpu.getPowerInterface().getSupportedPStates().containsKey("P0")) cpu.getPowerInterface().setPState("P0"); } } } } }}} == Application performance plugin == {{{ #!text/x-java public class DefaultTimeEstimationPlugin extends BaseTimeEstimationPlugin{ /* * This method should return an estimation of time required to execute the task. * Requested calculation should be done based on the resources allocated for the task, * task description and task completion percentage. * * Example implementation calculate the estimation based on cpu processing power. * There is also a simple assumption, that cpu processing power is a linear function * of number of allocated cpus and their speed. */ public double execTimeEstimation(SchedulingEvent event, ExecTask task, Map allocatedResources, double completionPercentage) { // collect all information necessary to do the calculation PEUnit peUnit = (PEUnit) allocatedResources.get(StandardResourceUnitName.PE); // obtain single pe speed int speed = peUnit.getSpeed(); // number of used pe int cnt = peUnit.getUsedAmount(); // estimate remainingTaskLength double remainingLength = task.getLength() * (1 - completionPercentage/100); // do the calculation double execTime = (remainingLength / (cnt * speed)); // if the result is very close to 0, but less then one millisecond then round this result to 0.001 if (Double.compare(execTime, 0.001) < 0) { execTime = 0.001; } // time is measured in integer units, so get the nearest execTime int value. execTime = Math.ceil(execTime); return execTime; } } }}} == Energy estimation plugin == === CPU energy estimation plugin === {{{ #!text/x-java public class CPUEnergyEstimationPlugin extends BaseEnergyEstimationPlugin { public double estimatePowerConsumption(EnergyEvent event, JobRegistry jobRegistry, ComputingResource resource) { double powerConsumption; Processor cpu = (Processor)resource; if(resource.getPowerInterface().getPowerState().equals(StandardPowerStateName.OFF)) powerConsumption = 0; else { try { return cpu.getPowerInterface().getPowerConsumption(cpu.getPowerInterface().getPState()); } catch (NoSuchFieldException e) { try { return cpu.getPowerInterface().getPowerConsumption(StandardPowerStateName.ON); } catch (NoSuchFieldException e1) { powerConsumption = 1; } } } return powerConsumption; } } }}} === Computing Node energy estimation plugin === {{{ #!text/x-java public class ComputingNodeEnergyEstimationPlugin extends BaseEnergyEstimationPlugin { public double estimatePowerConsumption(EnergyEvent event, JobRegistry jobRegistry, ComputingResource resource) { double powerConsumption = 0; ComputingNode node = (ComputingNode) resource; for(Processor cpu: node.getProcessors()){ powerConsumption = powerConsumption + cpu.getPowerInterface().getRecentPowerUsage().getValue(); } try { powerConsumption = powerConsumption + node.getPowerInterface().getPowerConsumption(node.getPowerInterface().getPowerState()); } catch (NoSuchFieldException e) { } return powerConsumption; } } }}}