This documentation helps you to create, edit, and execute adaptation process model instances based on the Descartes Modeling Language (DML). It explains how to use the provided model editors to specify adaptation processes and how to use the Adaptation Framework to execute the modeled adaptation process. To ease the start, we also provide several examples.
- 1 Installation Instructions
- 2 S/T/A Adaptation Process Modeling Language
- 3 Adaptation Framework
- 4 Technical Documentation
- 5 Troubleshooting
- 6 Examples
- 7 Publications
NOTE: For the installation instructions, see DML_Bench#Installation. The following installation instructions are outdated!
To simply execute a modeled adaptation process on the architecture-level performance model of a Descartes Modeling Language (DML) instance, it is sufficient to download and execute the jar file which can be obtained from this location (see Adaptation Framework for more details about how to execute the file). However, if you want to be able to view and edit DML model files including adaptation process models, we recommend to install the DML Editors. To do so, follow these steps:
- Download the Eclipse Modeling Package of Eclipse Luna (4.3)
- Extract and start Eclipse
- Install the DML Editors Feature
- Click on Help --> Intall New Software…
- Click on Add… to add this Update Site (currently only accessible from the Uni Würzburg subnet).
- Select the Descartes Modeling Editor Feature and click Next to install
- Restart Eclipse after installation
After restarting, you should be able to create and edit adaptation process models. Use these examples to get familiar with the meta-models and the editors.
S/T/A Adaptation Process Modeling Language
The adaptation process modeling language S/T/A is a domain-specific language to describe adaptation processes in dynamic environments (e.g., modern virtualized data centers). The S/T/A meta-model is specified in Ecore and part of the Descartes Modeling Language (DML). The adaptation process model uses other entities of the DML model, like structural information about the resource landscape and the application architecture, to specify adaptation strategies, tactics, and actions. More information about the concepts of S/T/A and DML can be found in these publications.
Currently, we provide a graphical tree editor to create or edit S/T/A model instances. We are also working on a textual editor to create S/T/A model instances in a programming language like fashion. These S/TA adaptation process model instances can be used as input for our prototype of an Adaptation Framework that interpret S/T/A adaptation process models and executes them on DML instances.
To create a new adaptation model, choose File --> New --> Other... . Then select Adaptation Model from the Example EMF Model Creation Wizards and click Next. Then, specify the location and the name of the file, click next. Then, choose Process from the list of Model Object and click Finish.
You can edit an existing model file by double-clicking it or right-click on the model file, then choose Open with --> Other... and select Adaptation Model Editor from the list.
If you followed the installation instructions on this page, you have installed the editors for the adaptation process model and other model editors for other model instances that can be created with DML. Thus you can view and edit all model files contained in our example, which is important to check the effect of an executed adaptation process.
The simplest way to execute the modeled adaptation process is to download the jar file from here (e.g., edu.kit.ipd.descartes.adaptation.executable-1.0.0-*-jar-with-dependencies.jar). This jar file contains all necessary parts to interpret and execute the adaptation process model. To run the framework, simply execute
java -jar adaptation_framework.jar your.properties
on the command line, pointing to the downloaded jar file and the properties file you want to use. This properties file specifies some meta-information as well as where to find the model instances that should be used. The properties file must specify the following entries:
|process.name||A string to name the executed adaptation process, for example: PushPull Adaptation Process.|
|process.maxiterations||An integer value specifying the maximum number of adaptation control loop iterations.|
|adaptationprocess.instance||A string specifying the path to the S/T/A model instance. If you use our example models, enter something like /path-to-your-workspace/Examples/SEAMS_Case_Study/pushpull.adaptation. Make sure that you specify the exact absolute path to your model file.|
|perfdatarepo.metamodel||A string pointing to the interface (the type of the root element) of your performance data repository|
|perfdatarepo.instance||A string pointing to the absolute path of the Performance Data Repository model instance.|
|event.type||The event type that triggers adaptation. Choose between SlaViolatedEventScheduled, OptimizationEvent, and BottleneckFoundEvent. The chosen event must be referenced by a strategy of the modeled adaptation process.|
The output of the adaptation framework is a changed DML model instance, e.g., the resource landscape, that has been given as input. In our example, the resource landscape model instance stored in the file acamarcluster.resourcelandscape has been adapted.
If you are interested in extending the adaptation process meta-model or the adaptation framework or if you want to get more technical information about the framework, have a look at this wiki page. However, this page is only for internal purposes at the moment.
We provide examples to explain how the editors work, how an adaptation process can look like, and how you can execute it with out framework. All examples can be downloaded as a single zip archive containing all necessary files. If you want to view and edit the model files with our editors, you have to import the examples into your Eclipse workspace by clicking on File --> Import --> Existing Projects Into Workspace --> Next. Then you choose Select archive file and browse for the downloaded archive to import the examples, then click Finish. Then, you should be able to see the example files in a new project in your workspace. You can edit these files by double-clicking them. Follow these instructions to view and/or edit model instances. To execute the adaptation process directly, use your command line tool and switch into the extracted folder (see these instructions).
NOTE: Make sure that you launch the adaptation framework from the Examples/ directory, otherwise you have to adjust the file paths in the properties files.
Dynamic Resource Allocation
This example contains the model instance we used for our case study with the SPECjEnterprise benchmark. All files necessary for this example are located in Examples/DynamicResourceAllocation_Case_Study/. The folder contains the following model instances:
- acamarcluster.resourcelandscape (The resource landscape model instance)
- default.adaptationpoints (The default set of adaptation points of the Acamar Cluster resource landscape)
- default.containerrepository (The set of default container templates used within the Acamar Cluster resource landscape)
- default.resourcetype (The default resource types in the Acamar Cluster resource landscape, e.g., CPU, HDD)
- pushpull.adaptation (The model instance of the PushPull Adaptation Process)
- simucomresults.observationrepo (A performance data repository filled with simulation results of different deployments in the Acamar Cluster resource landscape)
- metrictypes.perfdatarepo (The metrics available for specifying adaptation goals)
Furthermore, the folder contains the following configuration files:
- push.properties (The properties file that contains the configuration for the PUSH phase of the adaptation algorithm)
- pull.properties (The properties file that contains the configuration for the PULL phase of the adaptation algorithm)
- PUSH.launch (The launch configuration that can be used to launch the PUSH phase of the algorithm. This is only necessary if your want to launch the adaptation process from within Eclipse. However, to do this you need also the source code of the adaptation framework.)
- PUSH.launch (The launch configuration that can be used to launch the PULL phase of the algorithm. This is only necessary if your want to launch the adaptation process from within Eclipse. However, to do this you need also the source code of the adaptation framework.)
To launch the adaptation process, open your command line tool and change into the Examples directory. To start the PUSH phase of the algorithm, enter
java -jar <path/to/your/adaptation_framework.jar> DynamicResourceAllocation_Case_Study/push.properties
The command line output now shows what the adaptation framework is actually doing when interpreting the adaptation process. As a result, you see a changed acamarcluster.resourcelandscape model instance. Similarly, you can launch the pull phase by pointing to the pull.properties file.
Ressource Allocation in Heterogeneous Environments
This example models the resource landscape and adaptation process used in one of the case studies in the PhD thesis of Nikolaus Huber. The goal was to investigate how the approach can be used in a context of a heterogeneous resource environment and with multiple customers. The files for this example are located in Examples/BY_Case_Study/multiple_customers/. The folder contains the following files:
- by.resourcelandscape (The resource landscape model instance)
- default.adaptationpoints (The default set of adaptation points of the Blue Yonder resource landscape)
- by.containerrepository (The set of default container templates used within the Blue Yonder resource landscape)
- default.resourcetype (The default resource types in the resource landscape, e.g., CPU, HDD)
- metrictypes.xmi (The set of metrics stored in the PerformanceDataRepository and used by the adaptation process)
- by-multiple_customers.adaptation (The model instance of the adaptation process considering multiple customers)
- by-multiple_customers.pdr (A performance data repository containing data for multiple customer prediction server deployments)
- by-multiple_customers.properties (The properties file for the adaptation process)
- by-multiple_customers.lauch (A launch configuration for Eclipse)
To execute the adaptation process of our example, you have to perform the following steps.
1st Adaptation Phase (customer B increases workload)
The first adaptation phase is triggered because customer B has increased its workload which will lead to an SLA violation. The adaptation framework and the modeled adaptation process can be used to find a new system configuration as follows:
- Open your command line tool and change into the Examples/ directory
- Check if the paths to the model files in the properties file are correct
- Set event in the by-multiple_customers.properies file to WorkloadUpdate-CustomerB (This event indicates that customer B has increased its workload)
- Set latestObservation in the performance data repository by-multiple_customers.pdr to observations.0 (latestObservation="//@observations.0"). This is necessary because performance data is stored in the repository.
- Start adaptation with
java -jar <path/to/your/adaptation_framework.jar> BY_Case_Study/multiple_customers/by-multiple_customers.properties
- Check the results. The resource landscape model by.resourcelandscape should show one more prediction server instance for customer B (PS_CustB).
2nd Adaptation Phase (SLA of customer A violated)
Since the workload of customer B increased and required a new prediction server instance, the SLA of customer A are violated. We can use the adaptation framework to solve this as follows:
- Set event.type in the by-multiple_customers.properies file to SLAviolated-CustomerA (indicates SLA violation)
- Set latestObservation in by-multiple_customers.pdr to latestObservation="//@observations.1". This observation contains the measurements for the system configuration which resulted from the previous adaptation. This has to be adjusted manually since currently the adaptation framework is based on the performance data repository. This step is obsolete as soon as the prediction module is ready.
- Start adaptation with
java -jar <path/to/your/adaptation_framework.jar> BY_Case_Study/multiple_customers/by-multiple_customers.properties
- Check the results. The log output
Applied tactic 1: IncreaseResourcesOfCustomerA. Result ID: NoResult. Successful: false. Applied tactic 2: MigrateResourcesOfCustomerA. Result ID: NoResult. Successful: true. Applied tactic 3: MigrateResourcesOfCustomerA. Result ID: NoResult. Successful: true.
shows that adding more resources to customer A had no positive effect. Instead, the adaptation process migrates instances of customer A. Thus, the resource landscape model should now have an additional prediction server instance for customer A. Both instances are deployed on a separate machine (desc4).
- Nikolaus Huber. Autonomic Performance-Aware Resource Management in Dynamic IT Infrastructures. PhD thesis, Karlsruhe Institute of Technology (KIT), 2014. To be published, here's a preliminary version.
- Nikolaus Huber, André van Hoorn, Anne Koziolek, Fabian Brosig, and Samuel Kounev. Modeling Run-Time Adaptation at the System Architecture Level in Dynamic Service-Oriented Environments. Service Oriented Computing and Applications, 2014, Springer-Verlag. [ bib | .pdf ]
- Nikolaus Huber, André van Hoorn, Anne Koziolek, Fabian Brosig, and Samuel Kounev. S/T/A: Meta-Modeling Run-Time Adaptation in Component-Based System Architectures. In 9th IEEE International Conference on e-Business Engineering (ICEBE 2012), Hangzhou, China, September 9-11 2012. Acceptance Rate (Full Paper): 19.7% (26/132). [ bib | .pdf ]
- S. Kounev, F. Brosig, and N. Huber. Descartes Meta-Model (DMM). Technical report, Karlsruhe Institute of Technology (KIT), 2014. [ bib ] To be published, here's a preliminary version.