Finished Managing
diff --git a/brooklyn-docs/guide/glossary.json b/brooklyn-docs/guide/glossary.json
index 1f8b19d..b201aba 100644
--- a/brooklyn-docs/guide/glossary.json
+++ b/brooklyn-docs/guide/glossary.json
@@ -14,5 +14,9 @@
{
"term": "sensor, !<code>sensor",
"description": "A sensor is a property of an Apache Brooklyn entity, updated in real-time"
+ },
+ {
+ "term": "effector",
+ "description": "Effectors are tools Apache Brooklyn provides, that allow you to manipulate the live entities within an application"
}
-]
+]
\ No newline at end of file
diff --git a/brooklyn-docs/guide/start/managing.md b/brooklyn-docs/guide/start/managing.md
index be6ccce..3724590 100644
--- a/brooklyn-docs/guide/start/managing.md
+++ b/brooklyn-docs/guide/start/managing.md
@@ -56,7 +56,7 @@
Using the name `Tomcat` we can get the application details:
</p>
{% highlight bash %}
-$ br app Tomcat
+$ br application Tomcat
{% endhighlight %}
<pre>
Id: hTPAF19s
@@ -108,7 +108,7 @@
You can view the blueprint for the application again:
</p>
{% highlight bash %}
-$ br app tomcat spec
+$ br application Tomcat spec
{% endhighlight %}
<pre>
"name: Tomcat\nlocation:\n mylocation\nservices:\n- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer\n"
@@ -127,7 +127,7 @@
You can view the configuration of the application:
</p>
{% highlight bash %}
-$ br app tomcat config
+$ br application Tomcat config
{% endhighlight %}
<pre>
Key Value
@@ -146,7 +146,7 @@
To list the entities of the application you can use the `entity` or `ent` command:
{% highlight bash %}
-$ br app Tomcat entity
+$ br application Tomcat entity
{% endhighlight %}
<pre>
Id Name Type
@@ -158,7 +158,7 @@
You can get summary information for this entity by providing its name (or ID).
{% highlight bash %}
-$ br app Tomcat ent tomcatServer
+$ br application Tomcat entity tomcatServer
{% endhighlight %}
<pre>
Id: Wx7r1C4e
@@ -172,7 +172,7 @@
Also you can see the configuration of this entity with the ```config``` command.
{% highlight bash %}
-$ br app Tomcat ent tomcatServer config
+$ br application Tomcat entity tomcatServer config
{% endhighlight %}
<pre>
Key Value
@@ -186,12 +186,12 @@
## Sensors
-*Sensors* are properties which reflect the state of an *entity* and provide a real-time picture of an *entity* in an application.
+*Sensors* are properties which show the state of an *entity* and provide a real-time picture of an *entity* within an application.
-To view the sensors on the application itself, use the command below:
+You can view the sensors available on the application using:
{% highlight bash %}
-$ br app Tomcat sensor
+$ br application Tomcat sensor
{% endhighlight %}
<pre>
Name Description Value
@@ -202,11 +202,10 @@
service.state.expected Last controlled change to service state, indicating what the expected state should be "running @ 1450356994928 / Thu Dec 17 12:56:34 GMT 2015"
</pre>
-To explore all sensors available on an entity use the `sensor` command with an entity scope.
-Note, again, the name of the application or entity can be used or the ID:
+To explore sensors on a specific entity use the `sensor` command with an entity specified:
{% highlight bash %}
-$ br app Tomcat ent tomcatServer sensor
+$ br application Tomcat entity tomcatServer sensor
{% endhighlight %}
<pre>
Name Description Value
@@ -222,10 +221,10 @@
</pre>
-To study selected sensors, give the command the sensor name as an argument
+To display the value of a selected sensor, give the command the sensor name as an argument
{% highlight bash %}
-$ br app Tomcat ent tomcatServer sensor webapp.url
+$ br application Tomcat entity tomcatServer sensor webapp.url
{% endhighlight %}
<pre>
"http://10.10.10.101:8080/"
@@ -234,11 +233,10 @@
## Effectors
-Effectors are the means by which you can manipulate the entities in an application. For an application you can list them
-with
+Effectors are a means by which you can manipulate the entities in an application. You can list the available effectors for your application using:
{% highlight bash %}
-$ br app Tomcat effector
+$ br application Tomcat effector
{% endhighlight %}
<pre>
Name Description Parameters
@@ -247,10 +245,13 @@
stop Stop the process/service represented by an entity
</pre>
-For an entity supply the entity scope:
+For example, to stop an application, use the ```stop``` effector. This will cleanly shutdown all components in the application and return any cloud machines that were being used.
+Note that the three "lifecycle" related effectors, ```start```, ```stop```, and ```restart```, are common to all applications and software process entities in Brooklyn.
+
+You can list the effectors for a specific entity using the command:
{% highlight bash %}
-$ br app Tomcat ent tomcatServer effector
+$ br application Tomcat entity tomcatServer effector
{% endhighlight %}
<pre>
Name Description Parameters
@@ -262,70 +263,44 @@
undeploy Undeploys the given context/artifact targetName
</pre>
-To view just one effector's documentation, supply its name to the show command:
+To view the details for a specific effector, append it's name to the command:
{% highlight bash %}
-$ br app Tomcat ent tomcatServer effector deploy
-{% endhighlight %}
-<pre>
-Name Description Parameters
-deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
-</pre>
-
-These effectors can be invoked using the command ```invoke```, supplying the application and entity id of the entity to
-invoke the effector on.
-
-For example, to stop an application, use the ```stop``` effector. This will cleanly shutdown all components in the
-application and return any cloud machines that were being used. Do the invocation by supplying the effector name in
-the scope, and using the command ```invoke```.
-
-{% highlight bash %}
-$ br app Tomcat ent tomcatServer eff stop invoke
-{% endhighlight %}
-
-Note that the three "lifecycle" related effectors, ```start```, ```stop```, and ```restart```, are common to all software process
-entities in Brooklyn. They are so commonly used that they have their own aliases. The above could also have been done
-by:
-
-{% highlight bash %}
-$ br app Tomcat ent tomcatServer stop
-{% endhighlight %}
-
-Some effectors require parameters for their invocation, as in the example of ```deploy``` above.
-
-{% highlight bash %}
-$ br app Tomcat ent tomcatServer effector deploy
+$ br application Tomcat entity tomcatServer effector deploy
{% endhighlight %}
<pre>
Name Description Parameters
deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
</pre>
-Now the effector can be invoked by supplying the parameters using ```--param parm=value``` or just ```-P parm=value```.
+These effectors can also be invoked by appending ```invoke``` to this command. Some effectors require parameters for their invocation. For example, if we look at the details for ```deploy``` above we can see it requires a url and targetName.
-In the example below, a sample Tomcat war file is deployed, a variable is created for the root URL using the appropriate
-sensor, and the index page is fetched. Note that at present a ```tr``` command is required in the second line below to strip
-quotation characters from the returned sensor value.
+These parameters can be supplied using ```--param parm=value``` or just ```-P parm=value```.
+
+The commands below deploy the Apache Tomcat [hello world example](http://tomcat.apache.org/tomcat-6.0-doc/appdev/index.html){:target="_blank"} to our Tomcat Server. In these commands, a variable is created for the root URL using the appropriate
+sensor and the index page html is displayed.
{% highlight bash %}
-$ br app Tomcat ent tomcatServer effector deploy invoke -P url=https://tomcat.apache.org/tomcat-6.0-doc/appdev/sample/sample.war -P targetName=sample
-$ webapp=$(br app Tomcat ent tomcatServer sensor webapp.url | tr -d '"')
+$ br application Tomcat entity tomcatServer effector deploy invoke -P url=https://tomcat.apache.org/tomcat-6.0-doc/appdev/sample/sample.war -P targetName=sample
+$ webapp=$(br application Tomcat entity tomcatServer sensor webapp.url | tr -d '"')
$ curl $webapp/sample/
{% endhighlight %}
<html>
<head>
<title>Sample "Hello, World" Application</title>
</head>
-# etc. etc.
+ ...
+
+**Note** that at present a ```tr``` command is required in the second line below to strip quotation characters from the returned sensor value.
## Activities
-The ```activity``` command allows us to investigate the activities of an entity.
+*Activities* are the actions an application or entity takes within Apache Brooklyn. The ```activity``` command allows us to list out these activities.
-To view a list of all activities associated with an entity simply use
+To view a list of all activities associated with an entity enter:
{% highlight bash %}
-$ br app Tomcat ent tomcatServer activity
+$ br application Tomcat entity tomcatServer activity
{% endhighlight %}
<pre>
Id Task Submitted Status Streams
@@ -334,13 +309,13 @@
wLD764HE pre-start Thu Dec 17 15:04:43 GMT 2015 Completed
KLTxDkoa ssh: initializing on-box base dir ./b... Thu Dec 17 15:04:43 GMT 2015 Completed env,stderr,stdin,stdout
jwwcJWmF start (processes) Thu Dec 17 15:04:43 GMT 2015 Completed
-# etc. etc.
+...
</pre>
-To view the details of an individual activity provide its ID:
+To view the details of an individual activity, add its ID to the command. In our case this is `jwwcJWmF`
{% highlight bash %}
-$ br app Tomcat ent tomcatServer activity jwwcJWmF
+$ br application Tomcat entity tomcatServer activity jwwcJWmF
{% endhighlight %}
<pre>
Id: jwwcJWmF
@@ -361,13 +336,110 @@
No return value (null)"
</pre>
-If an activity has failed, the "DetailedStatus" value will show information about the failure, as an aid to diagnosis.
-Adding the ```--children``` or ```-c``` parameter will show the activity's child activities, to allow the hierarchical structure
-of the activities to be investigated:
+#### Things we might want to do
+<div class="panel-group" id="accordionB">
+ <div class="panel panel-default">
+ <div class="panel-heading">
+ <h4 class="panel-title">
+ <a data-toggle="collapse" data-parent="#accordionB" href="#collapseOneB">View Input and Output Streams</a>
+ </h4>
+ </div>
+ <div id="collapseOneB" class="panel-collapse collapse in">
+ <div class="panel-body">
+<p>
+If an activity has associated input and output streams, these may be viewed by providing the activity scope and
+using the commands, "env", "stdin", "stdout", and "stderr". For example, for the "initializing on-box base dir"
+activity from the result of the earlier example,
+</p>
{% highlight bash %}
-$ br app Tomcat ent tomcatServer activity -c jwwcJWmF
+$ br application Tomcat entity tomcatServer act KLTxDkoa stdout
+{% endhighlight %}
+<pre>
+BASE_DIR_RESULT:/home/vagrant/brooklyn-managed-processes:BASE_DIR_RESULT
+</pre>
+ </div>
+ </div>
+ </div>
+ <div class="panel panel-default">
+ <div class="panel-heading">
+ <h4 class="panel-title">
+ <a data-toggle="collapse" data-parent="#accordionB" href="#collapseTwoB">Monitor the progress of an effector</a>
+ </h4>
+ </div>
+ <div id="collapseTwoB" class="panel-collapse collapse">
+ <div class="panel-body">
+
+<p>
+To monitor progress on an application as it deploys, for example, one could use a shell loop:
+</p>
+{% highlight bash %}
+$ while br application Tomcat entity tomcatServer activity | grep 'In progress' ; do
+ sleep 1; echo ; date;
+done
+{% endhighlight %}
+<p>
+This loop will exit when the application has deployed successfully or has failed. If it fails then the 'stderr'
+command may provide information about what happened in any activities that have associated streams:
+</p>
+{% highlight bash %}
+$ br application Tomcat entity tomcatServer act KLTxDkoa stderr
+{% endhighlight %}
+
+ </div>
+ </div>
+ </div>
+ <div class="panel panel-default">
+ <div class="panel-heading">
+ <h4 class="panel-title">
+ <a data-toggle="collapse" data-parent="#accordionB" href="#collapseThreeB">Diagnose a failure</a>
+ </h4>
+ </div>
+ <div id="collapseThreeB" class="panel-collapse collapse">
+ <div class="panel-body">
+
+<p>
+If an activity has failed, the "DetailedStatus" value will help us diagnose what went wrong by showing information about the failure.
+</p>
+{% highlight bash %}
+$ br application evHUlq0n entity tomcatServer activity lZZ9x662
+{% endhighlight %}
+<pre>
+Id: lZZ9x662
+DisplayName: post-start
+Description:
+EntityId: qZeyoITy
+EntityDisplayName: tomcatServer
+Submitted: Mon Jan 25 12:54:55 GMT 2016
+Started: Mon Jan 25 12:54:55 GMT 2016
+Ended: Mon Jan 25 12:59:56 GMT 2016
+CurrentStatus: Failed
+IsError: true
+IsCancelled: false
+SubmittedByTask: hWU7Qvgm
+Streams:
+DetailedStatus: "Failed after 5m: Software process entity TomcatServerImpl{id=qZeyoITy} did not pass is-running check within the required 5m limit (5m elapsed)
+
+java.lang.IllegalStateException: Software process entity TomcatServerImpl{id=qZeyoITy} did not pass is-running check within the required 5m limit (5m elapsed)
+ at org.apache.brooklyn.entity.software.base.SoftwareProcessImpl.waitForEntityStart(SoftwareProcessImpl.java:586)
+ at org.apache.brooklyn.entity.software.base.SoftwareProcessImpl.postDriverStart(SoftwareProcessImpl.java:260)
+ at org.apache.brooklyn.entity.software.base.SoftwareProcessDriverLifecycleEffectorTasks.postStartCustom(SoftwareProcessDriverLifecycleEffectorTasks.java:169)
+ at org.apache.brooklyn.entity.software.base.lifecycle.MachineLifecycleEffectorTasks$PostStartTask.run(MachineLifecycleEffectorTasks.java:570)
+ at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
+ at org.apache.brooklyn.util.core.task.DynamicSequentialTask$DstJob.call(DynamicSequentialTask.java:342)
+ at org.apache.brooklyn.util.core.task.BasicExecutionManager$SubmissionCallable.call(BasicExecutionManager.java:468)
+ at java.util.concurrent.FutureTask.run(FutureTask.java:266)
+ at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
+ at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
+ at java.lang.Thread.run(Thread.java:745)"
+</pre>
+<p>
+Adding the "--children" or "-c" parameter will show the activity's child activities, to allow the hierarchical structure
+of the activities to be investigated:
+</p>
+{% highlight bash %}
+$ br application Tomcat entity tomcatServer activity -c jwwcJWmF
{% endhighlight %}
<pre>
Id Task Submitted Status
@@ -384,41 +456,23 @@
HKrYfH6h launch Thu Dec 17 15:08:58 GMT 2015 Completed
T1m8VXbq post-launch-command Thu Dec 17 15:08:59 GMT 2015 Completed
n8eK5USE post-launch Thu Dec 17 15:08:59 GMT 2015 Completed
-</pre>
-
-If an activity has associated input and output streams, these may be viewed by providing the activity scope and
-using the commands, ```env```, ```stdin```, ```stdout```, and ```stderr```. For example, for the "initializing on-box base dir"
-activity from the result of the earlier example,
-
-{% highlight bash %}
-$ br app Tomcat ent tomcatServer act KLTxDkoa stdout
-BASE_DIR_RESULT:/home/vagrant/brooklyn-managed-processes:BASE_DIR_RESULT
-{% endhighlight %}
+</pre>
+
+ </div>
+ </div>
+ </div>
+ </div>
-To monitor progress on an application as it deploys, for example, one could use a shell loop:
-
-{% highlight bash %}
-$ while br app Tomcat ent tomcatServer activity | grep 'In progress' ; do
- sleep 1; echo ; date;
-done
-{% endhighlight %}
-This loop will exit when the application has deployed successfully or has failed. If it fails then the 'stderr'
-command may provide information about what happened in any activities that have associated streams:
-
-{% highlight bash %}
-$ br app Tomcat ent tomcatServer act KLTxDkoa stderr
-{% endhighlight %}
-
-
+{::comment}
## Scopes in CLI commands
Many commands require a "scope" expression to indicate the target on which they operate. The scope expressions are
as follows (values in brackets are aliases for the scope):
- ```application``` APP-ID (app, a)
- Selects an application, e.g. "br app myapp"
+ Selects an application, e.g. "br application myapp"
- ```entity``` ENT-ID (ent, e)
- Selects an entity within an application scope, e.g. ```br app myapp ent myserver```
+ Selects an entity within an application scope, e.g. ```br application myapp entity myserver```
- ```effector``` EFF-ID (eff, f)
Selects an effector of an entity or application, e.g. ```br a myapp e myserver eff xyz```
- ```config``` CONF-KEY (conf, con, c)
@@ -428,10 +482,11 @@
For example
{% highlight bash %}
-$ br app Tomcat ent tomcatServer config
+$ br application Tomcat entity tomcatServer config
{% endhighlight %}
runs the ```config``` command with application scope of ```Tomcat``` and entity scope of ```tomcatServer```.
+{:/comment}
## Next
