From 7a290b9374f061fbe7008c875c2dc337164f5e33 Mon Sep 17 00:00:00 2001 From: Franck Chauvel Date: Mon, 22 Sep 2014 09:58:02 +0200 Subject: [PATCH] Adding more documentation in the companion site --- README | 91 +------------------ pom.xml | 35 +++++++- src/site/markdown/how_to_contribute.md | 65 ++++++++++++++ src/site/markdown/usage.md | 120 ++++++++++++++++++++++++- src/site/site.xml | 1 + 5 files changed, 223 insertions(+), 89 deletions(-) create mode 100644 src/site/markdown/how_to_contribute.md diff --git a/README b/README index df5c43f..80fe76d 100644 --- a/README +++ b/README @@ -32,92 +32,9 @@ In addition, a binary distribution, continuously updated, is available at: http://dist.thingml.org/trio/trio-dist.zip +3. PROJECT DOCUMENTATION +------------------------ -3. HOW TO RUN TRIO ------------------- +The documentation of Trio (in version 0.2-SNAPSHOT) is available at: -Trio is a java application, which should be run from the command line. The -following example show its primary usage. - - -Usage: trio [options] input.trio -where 'options' are: - -o, --observe=TAG the tag of the components whose activity shall be observed - -c, --control=TAG the tag of the components whose activity shall be controlled - -r, --runs=INTEGER the number of sample for statistical evidence - -t, --trace=FILE the file where the generated data shall be stored -Example: trio -o result.csv --run=10000 system.trio - - -Below is an example of output of succesful invocation - -$> java -jar trio-bundle.jar -o service -c infra -t trace.csv samples/sensapp_topo4.trio -Trio v0.1 -- Topology Robustness IndicatOr -Copyright (C) 2014 - SINTEF ICT -Licensed under LGPLv3 - -SYSTEM: SensApp, topology no. 4 -SCENARIO: Robustness of the 'service' layer to failure in the 'infra' layer -INDICATORS: - + Robustness: 0.0297 - + Five most sensitive components: - 1: 1.7375e+00 VM2 - 2: 8.2376e-01 VM1 - 3: 6.8183e-01 VM4 - 4: 6.6244e-01 VM3 - 5: 5.6873e-01 VM5 - + Five most harmful sequences: - 1: 1.9200e-01 [none, VM2] - 2: 5.6990e-02 [none, VM3, VM2] - 3: 5.2990e-02 [none, VM4, VM2] - 4: 5.1991e-02 [none, VM1, VM2] - 5: 3.1994e-02 [none, VM5, VM2] - -That's all folks! - - -4. HOW TO BUILD TRIO --------------------- - -$> mvn clean package - - - -5. HOW TO RELEASE TRIO ----------------------- - -Before to create a release, one should ensure the following: - - - Read/write access to the git repository - - - Valid credentials to connect on the "deployment" server are - configured in .m2/settings.xml - -The configuration of the SCM maven plugin can be tested using the -following command: - -$> mvn scm:validate - -Under Windows, one shall set up an ssh agent to avoid that the git -command hang waiting for a passphrase. The following commands are -necessary (run on the git-bash): - -$> eval `ssh-agent` -$> env | grep SSH -$> ssh-add "/c/Users/franckc/.ssh/id_rsa" - enter passphrase : XXXXXXXX - -The Maven release plugin can be run in a "dryRun" mode using the -option '-DdryRun=true-'. We recommend to get the 'dry run' before to -run the 'release:prepare' command. - -$> mvn --batch-mode release:prepare -DreleaseVersion=0.1 -DdevelopmentVersion=0.2-SNAPSHOT - -$> mvn release:perform - -If anything goes wrong during the prepare or perform command, on can -revert the info committed in the repository using the following -commands: - -$> git reset --hard -$> git push origin master --force \ No newline at end of file + http://fchauvel.github.io/trio/0.2-SNAPSHOT/ \ No newline at end of file diff --git a/pom.xml b/pom.xml index c7ff076..e417fb8 100644 --- a/pom.xml +++ b/pom.xml @@ -7,9 +7,16 @@ eu.diversify.trio 0.2-SNAPSHOT TRIO + http://fchauvel.github.com/trio + + TRIO is a simple domain specific language (DSL) used to describe the topology + of software deployment and to gain insight regarding their robustness. + + UTF-8 + github @@ -85,10 +92,17 @@ http://maven.thingml.org/archiva/repository/thingml-snapshot/ + + + github-pages + github-pages trought GitHub site plugin + http://fchauvel.github.com/trio + + - https://github.com/DIVERSIFY-project/disco/issues + https://github.com/fchauvel/trio/issues @@ -399,6 +413,25 @@ + + + com.github.github + site-maven-plugin + 0.10 + + Updating site for Trio ${project.version} + ${project.version} + true + + + + + site + + site + + + diff --git a/src/site/markdown/how_to_contribute.md b/src/site/markdown/how_to_contribute.md new file mode 100644 index 0000000..ebd66ed --- /dev/null +++ b/src/site/markdown/how_to_contribute.md @@ -0,0 +1,65 @@ +## How to contribute? + +### How to fetch the source code + +Trio is an open-source Java application, whose source code is available on +Github at the following address: + +https://github.com/fchauvel/trio/ + + +### How to build Trio + +The Trio code base follows the Maven convention. The project can be build, +tested, packaged and installed locally by running the command: + + $> mvn clean install + + +### How to release a new version + +Before to create a release, one should ensure the following: + + - Read/write access to the git repository + + - Valid credentials to connect on the "deployment" server are + configured in .m2/settings.xml + +The configuration of the SCM maven plugin can be tested using the +following command: + + $> mvn scm:validate + +Under Windows, one shall set up an ssh agent to avoid that the git +command hang waiting for a passphrase. The following commands are +necessary (run on the git-bash): + + $> eval `ssh-agent` + $> env | grep SSH + $> ssh-add "/c/Users/Bobby/.ssh/id_rsa" + enter passphrase : XXXXXXXX + +The Maven release plugin can be run in a "dryRun" mode using the +option '-DdryRun=true-'. We recommend to get the 'dry run' before to +run the 'release:prepare' command. + + $> mvn --batch-mode release:prepare -DdryRun=true -DreleaseVersion=0.1 -DdevelopmentVersion=0.2-SNAPSHOT + $> mvn --batch-mode release:prepare -Dresume=false -DreleaseVersion=0.1 -DdevelopmentVersion=0.2-SNAPSHOT + $> mvn release:perform + +If anything goes wrong during the 'perform' command, on can +revert the info committed in the repository using the following +commands: + + $> git reset --hard + $> git push origin master --force + +Tags that have been created by the release plugin will not be removed by the +previous commands, and must remove manually, as shown below. The first command +retrieves all the existing tags, and the next two remove and publish the removal +respectively. + + $> git tag + my-app-0.1 + $> git tag -d my-app-0.1 + $> git push origin :refs/tags/my-app-0.1 \ No newline at end of file diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md index e48470e..bf03cd1 100644 --- a/src/site/markdown/usage.md +++ b/src/site/markdown/usage.md @@ -27,4 +27,122 @@ the strength of the statistical evidence associated with the output indicators. The following command illustrates how to run TRIO from the command line - $> java -jar trio-final.jar my-deployment.json 1000 \ No newline at end of file +Trio is a java application, which should be run from the command line. The +following example show its primary usage. + + Usage: trio [options] input.trio + where 'options' are: + -o, --observe=TAG the tag of the components whose activity shall be observed + -c, --control=TAG the tag of the components whose activity shall be controlled + -r, --runs=INTEGER the number of sample for statistical evidence + -t, --trace=FILE the file where the generated data shall be stored + +Example: + + trio -o result.csv --run=10000 system.trio + +Below is an example of output of successful invocation + + $> java -jar trio-bundle.jar -o service -c infra -t trace.csv samples/sensapp_topo4.trio + Trio v0.1 -- Topology Robustness IndicatOr + Copyright (C) 2014 - SINTEF ICT + Licensed under LGPLv3 + + SYSTEM: SensApp, topology no. 4 + SCENARIO: Robustness of the 'service' layer to failure in the 'infra' layer + INDICATORS: + + Robustness: 0.0297 + + Five most sensitive components: + 1: 1.7375e+00 VM2 + 2: 8.2376e-01 VM1 + 3: 6.8183e-01 VM4 + 4: 6.6244e-01 VM3 + 5: 5.6873e-01 VM5 + + Five most harmful sequences: + 1: 1.9200e-01 [none, VM2] + 2: 5.6990e-02 [none, VM3, VM2] + 3: 5.2990e-02 [none, VM4, VM2] + 4: 5.1991e-02 [none, VM1, VM2] + 5: 3.1994e-02 [none, VM5, VM2] + + That's all folks! + + +### Describing the topology of the system + +The topology under study shall be described in a separate text file, as shown in the +example below, where we described the deployment of the SensApp system. SensApp is made +of five REST services (i.e., Admin, Notifier, Registry, Dispatcher and Storage), +that must be run on the top of servlet containers (SCX), themselves requiring +Java Runtime Environment (JRE) to run properly. The topology thus includes all +these services and the related platform as well as the underlying infrastructure +(physical or virtual machine) on which these software component are deployed. + + # + # The SensApp services and their dependencies + # + + system: + 'SensApp, topology no. 1' + + components: + - Admin requires Notifier and Registry and Storage and SC1 + - Notifier requires SC2 + - Registry requires Storage and SC2 + - Dispatcher requires Notifier and Registry and Storage and SC2 + - Storage requires DB and VM2 + - DB requires VM2 + - SC1 requires JRE1 + - SC2 requires JRE2 + - JRE1 requires VM1 + - JRE2 requires VM2 + - VM1 + - VM2 + + tags: + - 'infra' on VM1, VM2 + - 'platform' on DB, SC1, SC2, JRE1, JRE2 + - 'service' on Admin, Registry, Storage, Dispatcher, Notifier + + +The description of the system is made of three sections: "system", "components" +and "tags". + + - The "system" section associates a name to the system; + - the "components" section captures the topology as an assembly of components +(and their dependencies); + - the "tags" section let the user partitions the topology by arbitrarily +classifying components. + +Technical readers may found a complete description of the language used to +capture topologies in the associated ANTLR grammar, available at: +https://github.com/fchauvel/trio/blob/master/src/main/antlr4/eu/diversify/trio/builder/Trio.g4 + + +#### Expressing dependencies between components + +The most important section is the one entitled "components". It describes the +components (in the broadest meaning of the term) and their dependencies. Dependencies are +specified by the (optional) "requires" clause, which is followed by a logical condition +over the other components. For instance, in the above example, the expression: + + - Registry requires Storage and SC2 + +states that the "registry" service of SensApp will remain operational as long as +the Storage component and the underlying Servlet container (i.e., SC2) are +operational as well. These logical expressions will permit to propagate failures and, +in turn, to evaluate the robustness of the system. + +#### Partitioning the topology + +In many cases one may not be interested in the overall robustness, but in the +robustness of a subpart of the system with respect to failure of another. Trio let you +partition the topology by tagging the components in the "tag" section. For instance, +in the above example, the line: + + - 'infra' on VM1, VM2 + +states that both components "VM1" and "VM2" are tagged as "infra". Along with +other tagging clauses, they will permit to evaluate the robustness of the +infrastructure (so called "infra"), with respect to others partitions +(e.g., platform or services). diff --git a/src/site/site.xml b/src/site/site.xml index 75683f0..a0522d3 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -29,6 +29,7 @@ +