Adjusted Readmes

README.md

@@ -2,8 +2,7 @@
 [![build status](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/badges/master/pipeline.svg)](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/commits/master)
 
 MOCCI is an extension for the [Open Cloud Computing Interface (OCCI)](http://occi-wg.org/about/specification/) to enable a model-driven management of monitoring devices in the cloud, as well as storing their results within an OCCI-compliant runtime model. Together with other tools from the OCCI ecosystem it provides a testing and execution environment for self-adaptive systems.
-In the following you will find a getting started guide in which a preconfigured virtualbox image is downloaded to perform example scenarios and an tutorial on how to enrich existing OCCI models with monitoring functionality.
-Moreover, an introduction to MOCCI's components is provided, as well as links and description on how to integrate MOCCI with other pre-existing tooling from the OCCI ecosystem.
+In the following you will find a getting started guide in which a preconfigured virtualbox image is downloaded to perform example scenarios and an tutorial on how to enrich existing OCCI models with monitoring functionality. Moreover, an introduction to MOCCI's components is provided, as well as links and description on how to integrate MOCCI with other pre-existing tooling from the OCCI ecosystem. The paper submitted to this artifact and the virtualbox image can be found [here](https://owncloud.gwdg.de/index.php/s/5u2ddnyyNlzecM5) with the password bein mocci.
 
 
 ## Getting Started
@@ -11,7 +10,7 @@ To get started with MOCCI we provide a hands on experience in form of a virtualb
 Alternatively, to manually setup the single components instructions can be found at the end of this document.
 
 ### Download VirtualBox Image
-To get a quick start into MOCCI download the VM image located here:
+To get a quick start into MOCCI download the VM image (Mocci) located here:
 ```
 https://owncloud.gwdg.de/index.php/s/5u2ddnyyNlzecM5
 password: mocci
@@ -32,6 +31,7 @@ Next start the virtual machine:
 
 ### Execute Step-by-step example scenarios and tutorials
 To learn the ropes of MOCCI, we provide step-by-step instructions for three example scenarios, which are based on the same initial deployment model.
+It is recommended to execute the tutorials and examples in the following order:
 
 1. [Initial Deployment](doc/initial.md): This tutorial demonstrates how to deploy an initial cloud application getting monitored by MOCCI.
 2. [Vertical Scaling](doc/vertical.md): This scenario scales a VM in the initial deployment up and down according to its CPU utilization.

de.ugoe.cs.rwm.mocci.connector.dummy/README.md

 # Monitoring Extension Connector Dummy
-This component represents the connector dummy for the OCCI monitoring extension. The skeleton for this connector is generated using [OCCI-Studio](https://github.com/occiware/OCCI-Studio).
-Hereby, for each element in the monitoring extension a single connector file is present, implementing how to react on different REST requests addressing the corresponding OCCI element.
-This dummy is especially useful for testing purposes. Compared to the actual connector, a link to configuration management scripts is not necessary in order to get monitoring data.
+Each element in the monitoring extension has a single file in the connector implementing how to react on different REST requests addressing the corresponding OCCI element.
+This dummy is especially useful for testing purposes. Compared to the [connector](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/tree/master/de.ugoe.cs.rwm.mocci.connector) for an actual deployment of sensors, a link to configuration management scripts is not necessary in order to get monitoring data.
 As soon as a resultprovider is started monitoring results are simulated are passed to the monitorableproperty element of the sensor containing the resultprovider.
 The simulated values are easy to adjust and does not require a recompilation of the connector, as only the resultprovider.properties file within the connector has to be modified.
-
+The skeleton for the connector of the OCCI monitoring extension is generated using [OCCI-Studio](https://github.com/occiware/OCCI-Studio).
 
 
 ## Adjusting the Simulation
@@ -15,12 +14,18 @@ To configure the simulation of monitoring results the following steps have to be
 4. Adjust the values to your liking
 
 The adjustment of the file itself is best explained with a small example:
-Currently, the file contains the following:
+As default the file contains the following:
 ```
 CPU = None,Low,Medium,High,Critical,5000
 ```
-* CPU: Represents the monitorable.property to be adjusted.
-* 5000: Represents the interval in which monitoring.results are written.
-* None-Critical: Represents the simulated monitoring.results. 
 
+Hereby, the following information can be adjusted:
+* The first string (CPU): represents the monitorable.property to be adjusted by the simulation.
+* The last integer (5000): represents the interval in milliseconds in which a new monitoring.result is written.
+* Every string between (None-Critical): represents the values to be filled into the monitoring.result property.
 
+For example, to additionally generate monitoring results for MonitorableProperties having its monitoring.property set to Mem, the file could look like this:
+```
+CPU = None,Low,Medium,High,Critical,5000
+Mem = Save,Alert,10000
+```

de.ugoe.cs.rwm.mocci.connector/README.md

 # Monitoring Extension Connector
-This component represents the connector dummy for the OCCI monitoring extension. The skeleton for this connector is generated using [OCCI-Studio](https://github.com/occiware/OCCI-Studio).
-Hereby, for each element in the monitoring extension a single connector file is present, implementing how to react on different REST requests addressing the corresponding OCCI element.
-As the elements of the monitoring extension mainly inherit from elements of the enhanced platform extension provided by [MoDMaCAO](https://github.com/occiware/MoDMaCAO), the implementation of the lifecycle actions is quite similar. To handle the management of each individual component of a sensor, configuration management scripts have to be attached to them.
+Each element in the monitoring extension has a single file in the connector implementing how to react on different REST requests addressing the corresponding OCCI element.
+As the elements of the monitoring extension mainly inherit from elements of the enhanced platform extension provided by [MoDMaCAO](https://github.com/occiware/MoDMaCAO), the implementation of the lifecycle actions is quite similar. To handle the management of each individual component of a sensor, configuration management scripts have to be attached to them. Thus, in comparison to the [dummy connector](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/tree/master/de.ugoe.cs.rwm.mocci.connector.dummy), this connector allows for an actual deployment and management of sensors in a cloud environment. The skeleton for the connector of the OCCI monitoring extension is generated using [OCCI-Studio](https://github.com/occiware/OCCI-Studio).
 
 
 ## Attaching Configuration Management Scripts
@@ -16,5 +15,4 @@ actions as described in the configuration management script called glances, loca
 
 ![Attachment](./example.jpg "Attachment")
 
-
-
+*Note:* Currently, MoDMaCAO only provides a connector for [ansible](https://docs.ansible.com/).

de.ugoe.cs.rwm.mocci.model/README.md

 # Monitoring Extension
 This component represents the OCCI monitoring extension, we generated using [OCCI-Studio](https://github.com/occiware/OCCI-Studio).
 The elements introduced in this extension mainly inherit from elements of the enhanced platform extension of [MoDMaCAO](https://github.com/occiware/MoDMaCAO),
-as shown in the Figure below.
-
-![Ext](./monExt.jpg "Ext")
+as shown in the Figure below. As any other extension generated with OCCI-Studio the monitoring extension can be [registered as a plugin](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/blob/master/doc/studio.md) within Eclipse, OCCI-Studio, and the MartServer.
 
 ## The Sensor Element
 The sensor element represents a top level element used to easily manage all monitoring devices it contains.
@@ -15,9 +13,11 @@ To specify the object a sensor monitors, it can be connected over a monitorablep
 The property itself defines two attributes defining the name of the property it monitors, and its results.
 
 ## The Monitoring Components
-Each monitoring component (datagatherer, dataprocessor, resultprovider) inherit from component. 
+Each monitoring device (datagatherer, dataprocessor, resultprovider) inherit from component. 
 Thus, each monitoring component gains access to actions to deploy, configure, start, stop, and undeploy it.
 When not using the dummy connector, the execution of these actions trigger the execution of configuration management scripts linked to the individual monitoring device.
 The name of the scripts are assigned over user mixins attached to the component, which is located in the roles folder of the MartServer.
 To define where each monitoring device is deployed placementlinks are used connecting the device to the VM it is deployed on.
-Thus, each device can be hosted by different VM.
+Thus, each device can be hosted by different VM.
\ No newline at end of file
+
+![Ext](./monExt.jpg "Ext")
\ No newline at end of file

doc/initial.md

-# Initial Deployment Scenario
-In this scenario a hadoop cluster with one worker node getting monitored is deployed.
-This deployment serves as entry point for the other provided scenarios: [Vertical Scaling](./vertical.md), [Horizontal Scaling](./horizontal.md), and [Sensor Creation](./own.md).
+# Initial Deployment Tutorial
+In this tutorial a hadoop cluster with one worker node getting monitored is deployed. Therefore, the [MartServer](https://github.com/occiware/MartServer) is used in combination with [DOCCI](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.docci) an engine automatically deploying OCCI models.
+This deployment serves as entry point for the other provided scenarios: [Vertical Scaling](./vertical.md), [Horizontal Scaling](./horizontal.md), and [Sensor Creation](./own.md) showing how the monitored information can be used in self-adaptive control loops.
 
 ## Starting the MartServer
-To execute the scenario a MartServer has to be started including these [plugins](../src/test/resources/martserver-plugins).
 If the getting started VM is used everything is preconfigured only requiring to start the following script.
-Start a terminal and navigate to the desktop. The script can be started using the following command:
+Start a terminal(Strg-Alt-T) and navigate to the desktop (cd Desktop). The script can be started using the following command:
 ```
 ./startMART.sh
 ```
-*Note:* If this scenario is not performed in a running cloud environment consider executing the resetMart.sh script first.
+If the preconfigured VM is not used: Start the MartServer with these [plugins](../src/test/resources/martserver-plugins) for the test environemt.
+For an actual deployment in an OpenStack cloud we used the following [live connectors](../src/test/resources/martserver-plugins/live) including these [ansible roles](../src/test/resources/roles). 
 
 ## Deploying the Cluster
-Now the hadoop cluster can be deployed. Therefore, start the InitialDeployment.java file as an Java Application. This application performs requests to deploy the model shown below.
-If the VM is used: Open a terminal and navigate to the VM's desktop and execute the initialDeployment.jar. 
+Now that the MartServer is started the hadoop cluster can be deployed. Therefore, start the InitialDeployment.java file as an Java Application. This application performs requests to deploy the model shown below.
+If the VM is used: Open a terminal(Strg-Alt-T) and navigate to the VM's desktop(cd Desktop) and execute the initialDeployment.jar using the following command. 
 ```
 java -jar initialDeployment.jar
 ```
 
-After the deployment has been performed. The console running the MartServer puts out the simulated monitoring data in the following form:
+### Initial Deployment Application - Output
+During execution of the initialDeployment.jar the Executor of the deployment engine is logged. This log shows all OCCI requests that are executed to deploy the hadoop cluster model shown beneath.
+For example the network connecting the nodes in the hadoop cluster is created as shown in the following log output. The full log can be found [here](./initialLog.md):
+```
+2019-01-29 14:56:47 INFO  Executor:329 - PUT http://localhost:8080/network/urn:uuid:29d78078-fb4c-47aa-a9af-b8aaf3339591/ -H 'Content-Type: text/occi'  -H 'Category: network; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind", ipnetwork; scheme="http://schemas.ogf.org/occi/infrastructure/network#"; class="mixin"'  -H 'X-OCCI-Attribute:occi.core.id="urn:uuid:29d78078-fb4c-47aa-a9af-b8aaf3339591", occi.core.title="HNetwork", occi.core.summary="", occi.network.vlan="0", occi.network.label="", occi.network.state="active", occi.network.state.message="", occi.network.address="10.254.1.1/24"'
+```
+
+### MartServer - Output
+After the deployment has been performed. The sensors are started updating attached monitoring properties according to the interval specified in the dummy connector. The console running the MartServer puts out the simulated monitoring data in the following form:
 ```
 INFO MonProp: CPU, set to: High(ba16f4ee-1601-4192-a259-eae4274aed72)
+INFO MonProp: CPU, set to: Low(ba16f4ee-1601-4192-a259-eae4274aed72)
+INFO MonProp: CPU, set to: Critical(ba16f4ee-1601-4192-a259-eae4274aed72)
 ```
-Moreover, you can investigate the deployed OCCI model by opening your browser and query for OCCI entitites:
+
+
+### Browser - Output
+Now that everything has been deployed you can investigate the OCCI runtime model by opening your browser and query for OCCI entitites. In the following you find some example queries to query all compute, sensor, and monitorableproperties, as well as a query for the concrete monitored hadoop-worker compute node, and a filter for each monitorableproperty set to Critical. Additional query and filters can be found in the [documentation of the MartServer](https://github.com/occiware/MartServer/blob/master/doc/userdoc.md). It should be noted, that the updated MonitorableProperties can be investigated by **refreshing the browser**.
 ```
 http://localhost:8080/compute
 http://localhost:8080/sensor
 http://localhost:8080/monitorableproperty
+http://localhost:8080/compute/urn:uuid:2e6a73d0-faaa-476a-bd25-ca461dd166cf
+http://localhost:8080/monitorableproperty?attribute=monitoring.result&value=Critical
+
 ```
-The following figure visualized the initially deployed model:
-![Init](./src/main/resources/de/ugoe/cs/rwm/mocci/occi/initial.jpg "Init")
+
+Now that the deployed model shown below is running, the other tutorials can be executed. The following figure visualized the initially deployed model:
\ No newline at end of file
+![Init](./src/main/resources/de/ugoe/cs/rwm/mocci/occi/initial.jpg "Init")
+
+## Resetting the MartServer
+If you plan to execute the other scenarios([Vertical Scaling](./vertical.md), [Horizontal Scaling](./horizontal.md), and [Sensor Creation](./own.md)] do not reset the MartServer.
+Otherwise first stop the MartServer it by pressing Ctrl-C in the terminal running it. Thereafter, either start the resetMart.sh script or go to the folder holding the occi model of the MartServer(~/models) and delete the file model-anonymous.occic. This file represents the concrete runtime model stored by the MartServer when he is stopped and started.
\ No newline at end of file

doc/studio.md

@@ -4,7 +4,7 @@
 1. Download the [latest release of OCCI-Studio](https://github.com/occiware/OCCI-Studio/releases).
 2. Extract OCCI-Studio and start it.
 
-## Installing required plugins
+## Installing Required Plugins
 To initialize the proposed OCCI extensions, the following plugins need to be added to the OCCI-Studio. 
 These allow to correctly depict OCCI models in the textual and graphical editor. To Install plugins the following steps have
 to be performed:
@@ -23,9 +23,9 @@ To easily access our provided example install the gradle plugin within OCCI-Stud
 https://github.com/eclipse/buildship/blob/master/docs/user/Installation.md
 ```
 
-### Mocci
-Finally, the Mocci plugin can be installed which registers the OCCI monitoring extension. Therefore, the following steps have to be performed:
-1. Navigate to [https://rwm.pages.gwdg.de/de.ugoe.cs.rwm.mocci/model/index.html/](https://rwm.pages.gwdg.de/de.ugoe.cs.rwm.mocci/model/index.html/):
+### MOCCI
+Finally, the MOCCI plugin can be installed which registers the OCCI monitoring extension. Therefore, the following steps have to be performed:
+1. Navigate to [https://rwm.pages.gwdg.de/de.ugoe.cs.rwm.mocci/index.html](https://rwm.pages.gwdg.de/de.ugoe.cs.rwm.mocci/index.html):
 2. Press Download Eclipse Plugin Archive
 3. Save the updatesite.zip to any destination
 4. Then follow the steps to install the plugin given above, but system choose the location of the updatesite.zip
@@ -35,7 +35,7 @@ Alternatively, you can build the Eclipse plugin yourself by checking out the pro
 gradle updateSiteZip
 ```
 
-## Visualizing the example
+## Visualizing The Example
 Now that the IDE has been installed and configured, the example model can now be loaded, visualized, and edited.
 The model can be found within the project under:
 ```

doc/vertical.md

@@ -2,40 +2,66 @@
 Prerequisite for this scenario is the [initial deployment](./initial.md) of the hadoop cluster.
 Thereafter, a MAPE-k loop is initialized that periodically checks whether the CPU utilization of the worker node reaches a critical level.
 If that is the case a request against the OCCI API is performed, increasing the number of cores and memory available to the machine.
+This scenario serves as an example showing how to directly work with the OCCI interface only requiring the execution of REST requests.
 
 ## Starting the Adaptation Script
 In this scenario, a simple bash script is used to check the gathered monitoring data and perform corresponding actions.
-This scenario serves as an example on how to directly work with the OCCI API, including the monitoring extension, by simply writing small bash scripts.
 Before the adaptation script is started make sure that the MartServer is running and the hadoop cluster has been deployed.
 To start the script execute the [vertical.sh](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/blob/master/src/main/resources/vertical.sh) script.
-In the getting started VM the script is located on the desktop. Create a terminal navigate to the desktop and start the script with the following command:
+In the getting started VM the script is located on the desktop. Create a terminal(Ctrl-Alt-T) navigate to the desktop(cd Desktop) and start the script with the following command:
 ```
 ./vertical.sh
 ```
 
-When a critical cpu utilization is present in the model the monitored VM is upscaled from 2 to 8 cores.
-Otherwise it is downscaled to 2 cores. The current amount of cores can be easiest checked by querying the compute node using a browser:
+### Adaptation Script - Output
+The output of the script is separated into the individual steps of the MAPE loop: Monitor, Analyze, Plan, and Execute.
+Thus, the output looks depending on the adaptive action to be performed similar to:
 ```
-http://localhost:8080/compute/urn:uuid:2e6a73d0-faaa-476a-bd25-ca461dd166cf/
+Starting MAPE script
+Requesting http://localhost:8080/monitorableproperty?attribute=monitoring.result&value=Critical every 3 seconds!
+Monitor
+{
+  "id" : "urn:uuid:ba16f4ee-1601-4192-a259-eae4274aed72",
+  "kind" : "http://schemas.ugoe.cs.rwm/monitoring#monitorableproperty",
+  "mixins" : [ ],
+  "attributes" : {
+    "monitoring.property" : "CPU",
+    "monitoring.result" : "Critical"
+  },
+  "actions" : [ ],
+  "location" : "/monitorableproperty/urn:uuid:ba16f4ee-1601-4192-a259-eae4274aed72",
+  "source" : {
+    "location" : "/sensor/urn:uuid:efb0f50a-7a7c-4153-b939-4846d6554dbb",
+    "kind" : "http://schemas.ugoe.cs.rwm/monitoring#sensor"
+  },
+  "target" : {
+    "location" : "/compute/urn:uuid:2e6a73d0-faaa-476a-bd25-ca461dd166cf",
+    "kind" : "http://schemas.ogf.org/occi/infrastructure#compute"
+  }
+}
+Analyze
+Critical Compute Detected
+Plan: Scale up VM
+State: DownScaled
+Execute
+
 ```
+In this case the query for VMs detects a Critical CPU utilization resulting in the "Scale up VM" plan. As the current state of the VM which is stored by the script is set to DownScaled a REST request adjusting the amount of cores of the VM is executed. Hereby, the occi.compute.cores attribute is updated from 2 to 8 cores. If the VM has currently has 8 cores and a downscale  plan is executed the amount of cores is set to 2.
 
-*Note:* This scenario mainly serves to get started with the OCCI API. Currently, there is no connector implementing the vertical adjustment as shown in this scenario.
+Independent of which plan gets executed the REST response is printed in the terminal executing the script.
+The response shows the complete information about the updated VM, including its Links, which is rather large.
+An example log file from the execution of the script can be found [here](./verticalLog.md).
 
-## Tuning the Scenario
-As the adaptation only upscales on a Critical behavior, it may be interesting to tune the simulated monitoring results.
-Therefore, the following steps have to be performed:
-1. Stop the MartServer (CTRL-C)
-2. Navigate to ~/martserver-plugins
-3. Open the de.ugoe.cs.rwm.mocci.connecter.dummy.jar with the archive manager.
-4. Doubleclick on the resultprovider.properties file
-5. Adjust the values to your liking
-
-The file contains the following:
+
+### Browser - Output
+Again, the browser can be used to query the running OCCI model. As the self-adaptation script adjusts the amount of cores of the worker node in the hadoop cluster, the compute node can be directly queries to gain information about its current state.
+Therefore, investigate the occi.compute.core attribute of the worker node using the following query: 
 ```
-CPU = None,Low,Medium,High,Critical,5000
+http://localhost:8080/compute/urn:uuid:2e6a73d0-faaa-476a-bd25-ca461dd166cf/
 ```
-* CPU: Represents the monitorable.property to be adjusted.
-* 5000: Represents the interval in which monitoring.results are written.
-* None-Critical: Represents the simulated monitoring.results. 
 
-*Note;* If you want to execute the second scenario please bring the resultprovider.properties file to its original state. 
+## Tuning the Scenario
\ No newline at end of file
+As the adaptation only upscales on a Critical behavior, it may be interesting to tune the simulated monitoring results.
+Therefore, follow the steps defined the documentation of the [dummy connector](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/tree/master/de.ugoe.cs.rwm.mocci.connector.dummy).
+
+*Note*: This scenario mainly serves to get started with the OCCI API. Currently, there is no connector implementing the vertical adjustment as shown in this scenario.
\ No newline at end of file