You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by sj...@apache.org on 2016/01/05 12:16:26 UTC
[04/10] incubator-brooklyn git commit: Updated blueprint-cli and
managing-cli.
Updated blueprint-cli and managing-cli.
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/36e2f14a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/36e2f14a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/36e2f14a
Branch: refs/heads/master
Commit: 36e2f14a832bd1f3b21af5e104236347d0bc05d8
Parents: 2966a44
Author: Geoff Macartney <ge...@cloudsoftcorp.com>
Authored: Thu Dec 17 16:44:31 2015 +0000
Committer: Geoff Macartney <ge...@cloudsoftcorp.com>
Committed: Wed Dec 23 12:24:56 2015 +0000
----------------------------------------------------------------------
brooklyn-docs/website/index.md | 1 +
docs/guide/start/blueprints-cli.md | 22 +-
docs/guide/start/managing-cli.md | 349 +++++++++++++++++---------------
docs/guide/start/policies-cli.md | 1 +
4 files changed, 202 insertions(+), 171 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/36e2f14a/brooklyn-docs/website/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/index.md b/brooklyn-docs/website/index.md
index 1312fdc..7f2f56e 100644
--- a/brooklyn-docs/website/index.md
+++ b/brooklyn-docs/website/index.md
@@ -6,6 +6,7 @@ children:
- learnmore/
- { path: download/, menu: null }
- { path: /guide/start/index.md, title_in_menu: Get Started, href_path: /guide/start/running.md}
+- { path: /guide/start/index-cli.md, title_in_menu: CLI Get Started, href_path: /guide/start/index-cli.md}
- path: documentation/
menu:
- { path: /guide/index.md, title_in_menu: "User Guide",
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/36e2f14a/docs/guide/start/blueprints-cli.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/blueprints-cli.md b/docs/guide/start/blueprints-cli.md
index d7c80ec..8df9d0d 100644
--- a/docs/guide/start/blueprints-cli.md
+++ b/docs/guide/start/blueprints-cli.md
@@ -12,7 +12,9 @@ children:
We'll start by deploying an application with a simple YAML blueprint containing a Tomcat server.
-Copy the blueprint below into a text file, "myapp.yaml", in your workspace, but *before* you create an application with it, modify the YAML to specify the location where the application will be deployed.
+Copy the blueprint below into a text file, "myapp.yaml", in your workspace, but *before* you create an application with
+it, modify the YAML to specify the location where the application will be deployed. (Note, to copy the file you can
+hover your mouse over the right side of the text box below to get a Javascript "copy" button.)
{% highlight yaml %}
name: Tomcat
@@ -24,7 +26,8 @@ services:
- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer
{% endhighlight %}
-Replace the `location:` element with values for your chosen target environment, for example to use SoftLayer rather than AWS (updating with your own credentials):
+Replace the `location:` element with values for your chosen target environment, for example to use SoftLayer rather
+than AWS (updating with your own credentials):
{% highlight yaml %}
location:
@@ -47,7 +50,9 @@ location:
- 192.168.0.19
{% endhighlight %}
-**Note**: See __[Locations](../ops/locations)__ in the Operations section of the User Guide for instructions on setting up alternate cloud providers, bring-your-own-nodes, or localhost targets, and storing credentials/locations in a file on disk rather than in the blueprint.
+**Note**: See __[Locations](../ops/locations)__ in the Operations section of the User Guide for instructions on setting
+up alternate cloud providers, bring-your-own-nodes, or localhost targets, and storing credentials/locations in a file
+on disk rather than in the blueprint.
(For the application above, if you are using a "Bring your own Nodes" location, you will need at least three nodes.)
First you will have to log in to brooklyn:
@@ -55,15 +60,20 @@ First you will have to log in to brooklyn:
$ br login http://localhost:8081/
{% endhighlight %}
-To secure the server you can add a username and password in Brooklyn's properties file, as described in the User Guide. Then the login command will require the additional parameters of the userid and password.
+To secure the server you can add a username and password in Brooklyn's properties file, as described in the User Guide.
+Then the login command will require the additional parameters of the userid and password.
Now you can create the application with the command below:
{% highlight bash %}
-$ br add application myapp.yaml
+$ br deploy myapp.yaml
+Id: hTPAF19s
+Name: Tomcat
+Status: In progress
{% endhighlight %}
-Depending on your choice of location it may take some time for the application to start, the next page describes how you can monitor the progress of the application deployment and verify its successful deployment.
+Depending on your choice of location it may take some time for the application to start, the next page describes how
+you can monitor the progress of the application deployment and verify its successful deployment.
## Launching from the Catalog
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/36e2f14a/docs/guide/start/managing-cli.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/managing-cli.md b/docs/guide/start/managing-cli.md
index d98f1d7..721c2c9 100644
--- a/docs/guide/start/managing-cli.md
+++ b/docs/guide/start/managing-cli.md
@@ -2,138 +2,133 @@
title: Monitoring and Managing Applications
title_in_menu: Monitoring and Managing Applications
layout: website-normal
-menu_parent: index.md
+menu_parent: index-cli.md
+children:
+- { section: Applications }
+- { section: Entities }
+- { section: Sensors }
+- { section: Effectors }
+- { section: Activities }
---
-So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, but this just the beginning, proceed to **[Monitoring and Managing Applications](managing.html)**.
+So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, but this just
+the beginning. The sections below outline how to manage the application that has been deployed.
+## Applications
-## Monitoring and Managing Applications
-
-Having created the application we can query its status:
-{% highlight yaml %}
-$ br list application
-Id Name Status Location
-MkGDqcQc Tomcat STARTING cu8846Za
+Having created the application we can query its status. We can find a summary of all deployed apps:
+{% highlight bash %}
+$ br app
+ Id Name Status Location
+ hTPAF19s Tomcat RUNNING ajVVAhER
{% endhighlight %}
-or [DISCUSS - note the full name of the application need not be supplied.] The ID, MkGDqcQc, can also be used instead of the name "Tomcat".
-{% highlight yaml %}
-$ br show application Tomcat
-Id Name Status Location
-MkGDqcQc Tomcat STARTING KNTBdBkh
+or the details of a given app. The ID, hTPAF19s, can also be used instead of the name "Tomcat".
+{% highlight bash %}
+$ br app Tomcat
+ Id: hTPAF19s
+ Name: Tomcat
+ Status: RUNNING
+ ServiceUp: true
+ Type: org.apache.brooklyn.entity.stock.BasicApplication
+ CatalogItemId: null
+ LocationId: ajVVAhER
+ LocationName: FixedListMachineProvisioningLocation:ajVV
+ LocationSpec: vagrantbyon
+ LocationType: org.apache.brooklyn.location.byon.FixedListMachineProvisioningLocation
{% endhighlight %}
-We can wait until the status changes by using "waitfor":
-{% highlight yaml %}
-$ br waitfor application MkGDqcQc
-...[a pause until the application starts]...
-Name Id Status Location
-MkGDqcQc Tomcat RUNNING KNTBdBkh
+To ease management of multiple applications, or even to reduce the amount of typing required, it is convenient
+to create an alias for the commonly used application scope:
+{% highlight bash %}
+alias tom="br app Tomcat"
{% endhighlight %}
-By default this will time out after five minutes, but this can be changed by supplying a ```--timeout``` parameter (see details in the CLI Guide [provide a link].
-
+However, for simplicity the examples below show the full command in all cases.
-We can explore the management hierarchy of the application, which will show us the entities it is composed of.
-{% highlight yaml %}
-$ br show -r application MkGDqcQc
+We can explore the management hierarchy of all applications, which will show us the entities they are composed of.
+{% highlight bash %}
+$ br tree
|- Tomcat
+- org.apache.brooklyn.entity.stock.BasicApplication
- |- TomcatServer:SjJ6
+ |- TomcatServer:Wx7r
+- org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
{% endhighlight %}
-Other options for the "show" command include:
-{% highlight yaml %}
-$ br show --status application MkGDqcQc
-Status RUNNING
-Service Up true
-Type org.apache.brooklyn.entity.stock.BasicApplication
-ID MkGDqcQc
-Catalog Item null
-{% endhighlight %}
You can view the blueprint for the application again:
-{% highlight yaml %}
-$ br show --blueprint application MkGDqcQc
-name: Tomcat
-
-services:
-...etc
+{% highlight bash %}
+$ br app Tomcat spec
+"name: Tomcat\nlocation:\n mylocation\nservices:\n- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer\n"
{% endhighlight %}
You can view the config of the application:
-{% highlight yaml %}
-$ br show --config application MkGDqcQc
-Name Value
-brooklyn.wrapper_app true
-camp.template.id IUDK7rrs
+{% highlight bash %}
+$ br app Tomcat config
+Key Value
+camp.template.id l67i25CM
+brooklyn.wrapper_app true
{% endhighlight %}
## Entities
-To explore the entities of the application you can use the "list entity" command. This will show the
+To explore the entities of the application you can use the "entity" command. This will show the
immediate child entities of a given application or one of its child entities.
-{% highlight yaml %}
-$ br list entity MkGDqcQc
+{% highlight bash %}
+$ br app Tomcat entity
Id Name Type
-SjJ6TDsR TomcatServer:SjJ6 org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+Wx7r1C4e TomcatServer:Wx7r org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
{% endhighlight %}
-For a more complex entity than our Tomcat example it may be informative to list the entities recursively with -r.
-
+You can get summary information for an entity by providing its name (or ID).
-You can get summary information for an entity with "show":
-
-{% highlight yaml %}
-$ br show entity MkGDqcQc SjJ6TDsR
-Status RUNNING
-Service Up true
-URL http://10.10.10.101:8080/
-Type org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
-ID SjJ6TDsR
-Catalog Item null
+{% highlight bash %}
+$ br app Tomcat entity TomcatServer:Wx7r
+Id: Wx7r1C4e
+Name: TomcatServer:Wx7r
+Status: RUNNING
+ServiceUp: true
+Type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+CatalogItemId: null
{% endhighlight %}
-Also you can see the config of the entity by adding the "--config" parameter.
-
-{% highlight yaml %}
-$ br show entity --config MkGDqcQc SjJ6TDsR
+Also you can see the config of the entity with the "config" command.
-Name Value
-brooklyn.wrapper_app true
-camp.template.id C2JbRPCR
-install.unique_label TomcatServer_7.0.65
-jmx.agent.mode JMXMP_AND_RMI
-onbox.base.dir /home/vagrant/brooklyn-managed-processes
-onbox.base.dir.resolved true
+{% highlight bash %}
+$ br app Tomcat entity TomcatServer:Wx7r config
+Key Value
+jmx.agent.mode JMXMP_AND_RMI
+brooklyn.wrapper_app true
+camp.template.id yBcQuFZe
+onbox.base.dir /home/vagrant/brooklyn-managed-processes
+onbox.base.dir.resolved true
+install.unique_label TomcatServer_7.0.65
{% endhighlight %}
## Sensors
"Sensors" on entities provide a real-time picture of the status and operation of an entity of the application.
-To view the sensors on the application itself, use the command "list sensor <APPID> <APPID>":
+To view the sensors on the application itself, use the command below:
{% highlight bash %}
-$ br list sensor Tomcat Tomcat
+$ br app Tomcat sensor
Name Description Value
service.isUp Whether the service is active and availability (confirmed and monitored) true
service.notUp.indicators A map of namespaced indicators that the service is not up {}
service.problems A map of namespaced indicators of problems with a service {}
-service.state.expected Last controlled change to service state, indicating what the expected state should be "running @ 1448895058652 / Mon Nov 30 14:50:58 GMT 2015"
service.state Actual lifecycle state of the service "RUNNING"
+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"
{% endhighlight %}
-To explore all sensors available on an entity use the command "list sensor <APPID> <ENTITYID>". Note, again the
-name of the application or entity can be used instead of the ID:
+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:
{% highlight bash %}
-$ br sensors Tomcat TomcatServer:SjJ6
+br app Tomcat ent TomcatServer:Wx7r sensor
Name Description Value
download.addon.urls URL patterns for downloading named add-ons (will substitute things like ${version} automatically)
download.url URL pattern for downloading the installer (will substitute things like ${version} automatically) "http://download.nextag.com/apache/tomcat/tomcat-7/v${version}/bin/apache-tomcat-${version}.tar.gz"
@@ -143,103 +138,35 @@ host.name Host name
host.sshAddress user@host:port for ssh'ing (or null if inappropriate) "vagrant@10.10.10.101:22"
host.subnet.address Host address as known internally in the subnet where it is running (if different to host.name) "10.10.10.101"
host.subnet.hostname Host name as known internally in the subnet where it is running (if different to host.name) "10.10.10.101"
-http.port HTTP port 8080
-https.port HTTP port (with SSL/TLS) 8443
-install.dir Directory for this software to be installed in "/home/vagrant/brooklyn-managed-processes/installs/TomcatServer_7.0.65"
-java.metrics.heap.committed Commited heap size (bytes) "203 MB"
-java.metrics.heap.init Initial heap size (bytes) "210 MB"
-java.metrics.heap.max Max heap size (bytes) "811 MB"
-java.metrics.heap.used Current heap size (bytes) "10.5 MB"
-java.metrics.nonheap.used Current non-heap size (bytes) "16.6 MB"
-java.metrics.physicalmemory.free The free memory available to the operating system "75.7 MB"
-java.metrics.physicalmemory.total The physical memory available to the operating system "514 MB"
-java.metrics.processCpuTime.fraction.last Fraction of CPU time used, reported by JVM (percentage, last datapoint) "0.3998%"
-java.metrics.processCpuTime.fraction.windowed Fraction of CPU time used, reported by JVM (percentage, over time window) "0.3998%"
-java.metrics.processCpuTime.total Process CPU time (total millis since start) "12.1s"
-java.metrics.processors.available number of processors available to the Java virtual machine 2
-java.metrics.starttime Start time of Java process (UTC) "2015-11-30 14:51:57.357"
-java.metrics.systemload.average average system load 0.0
-java.metrics.threads.current Current number of threads 33
-java.metrics.threads.max Peak number of threads 34
-java.metrics.uptime Uptime of Java process (millis, elapsed since start) "33m 59s"
-jmx.agent.local.path Path to JMX driver on the local machine "/home/vagrant/brooklyn-managed-processes/apps/MkGDqcQc/entities/TomcatServer_SjJ6TDsR/brooklyn-jmxmp-agent-shaded-0.9.0-SNAPSHOT.jar"
-jmx.context JMX context path "jmxrmi"
-jmx.direct.port JMX direct/private port (e.g. JMX RMI server port, or JMXMP port, but not RMI registry port) 31001
-jmx.direct.port.legacy.NOT_USED Legacy definition JMX direct/private port (e.g. JMX RMI server port, or JMXMP port, but not RMI registry port)
-jmx.password JMX password
-jmx.service.url The URL for connecting to the MBean Server "service:jmx:jmxmp://10.10.10.101:31001"
-jmx.user JMX username
-log.location Log file location "/home/vagrant/brooklyn-managed-processes/apps/MkGDqcQc/entities/TomcatServer_SjJ6TDsR/logs/catalina.out"
-main.uri Main URI for contacting the service/endpoint offered by this entity "http://10.10.10.101:8080/"
-rmi.registry.port RMI registry port, used for discovering JMX (private) port 1099
-run.dir Directory for this software to be run from "/home/vagrant/brooklyn-managed-processes/apps/MkGDqcQc/entities/TomcatServer_SjJ6TDsR"
-service.isUp Whether the service is active and availability (confirmed and monitored) true
-service.notUp.diagnostics A map of namespaced diagnostics, from when the service is not up {}
-service.notUp.indicators A map of namespaced indicators that the service is not up {}
-service.process.isRunning Whether the process for the service is confirmed as running true
-service.state Actual lifecycle state of the service "RUNNING"
-service.state.expected Last controlled change to service state, indicating what the expected state should be "running @ 1448895119929 / Mon Nov 30 14:51:59 GMT 2015"
-softwareprocess.pid.file PID file
-softwareservice.provisioningLocation Location used to provision a machine where this is running {"type":"org.apache.brooklyn.api.location.Location","id":"cu8846Za"}
-tomcat.shutdownport Suggested shutdown port 31880
-webapp.deployedWars Names of archives/contexts that are currently deployed []
-webapp.enabledProtocols List of enabled protocols (e.g. http, https) ["http"]
-webapp.https.ssl SSL Configuration for HTTPS
-webapp.reqs.bytes.received Total bytes received by the webserver ""
-webapp.reqs.bytes.sent Total bytes sent by the webserver ""
-webapp.reqs.errors Request errors 2
-webapp.reqs.perSec.last Reqs/sec (last datapoint) 0.0
-webapp.reqs.perSec.windowed Reqs/sec (over time window) 0.0
-webapp.reqs.processingTime.fraction.last Fraction of time spent processing, reported by webserver (percentage, last datapoint) "0%"
-webapp.reqs.processingTime.fraction.windowed Fraction of time spent processing, reported by webserver (percentage, over time window) "0%"
-webapp.reqs.processingTime.max Max processing time for any single request, reported by webserver (millis) ""
-webapp.reqs.processingTime.total Total processing time, reported by webserver (millis) "41ms"
-webapp.reqs.total Request count 2
-webapp.tomcat.connectorStatus Catalina connector state name "STARTED"
-webapp.url URL "http://10.10.10.101:8080/"
+# etc. etc.
{% endhighlight %}
-To study selected sensors, use the command "show sensor <APPID> <ENTITYID> <SENSOR>". Here, SENSOR can be the name
-of an individual sensor, e.g.
+To study selected sensors, give the command the sensor name as an argument
{% highlight bash %}
-$ br show sensor MkGDqcQc SjJ6TDsR MkGDqcQc SjJ6TDsR webapp.url
+$ br app Tomcat ent TomcatServer:Wx7r sensor webapp.url
"http://10.10.10.101:8080/"
{% endhighlight %}
-In this case only the value of the sensor is returned.
-
-Alternatively you can supply the "list sensor" command an item of text that may match multiple sensors (using a "globbing" syntax like the unix command line):
-
-
-{% highlight bash %}
-$ br list sensor MkGDqcQc SjJ6TDsR service.isUp "webapp.reqs.per*"
-Name Description
-webapp.reqs.perSec.last Reqs/sec (last datapoint) 0.0
-webapp.reqs.perSec.windowed Reqs/sec (over time window) 0.0
-{% endhighlight %}
-
## Effectors
Effectors are the means by which you can manipulate the entities in an application. For an application you can list them
-with "bk list effector <APPID>":
+with
{% highlight bash %}
-$ br list effector MkGDqcQc MkGDqcQc
+$ br app Tomcat effector
Name Description Parameters
restart Restart the process/service represented by an entity
start Start the process/service represented by an entity locations
stop Stop the process/service represented by an entity
{% endhighlight %}
-Note that these three "lifecycle" related effectors, start, stop, and restart, are common to all software process entities in Brooklyn.
-
-For an entity supply the entity id:
+For an entity supply the entity scope:
{% highlight bash %}
-$ br list effector MkGDqcQc SjJ6TDsR
+$ br app Tomcat ent TomcatServer:Wx7r effector
Name Description Parameters
deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
populateServiceNotUpDiagnostics Populates the attribute service.notUp.diagnostics, with any available health indicators
@@ -252,33 +179,125 @@ undeploy Undeploys the given context/artifact
To view just one effector's documentation, supply its name to the show command:
{% highlight bash %}
-$ br show effector MkGDqcQc SjJ6TDsR deploy
+$ br app Tomcat ent TomcatServer:Wx7r effector deploy
Name Description Parameters
deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
{% endhighlight %}
-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.
+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:Wx7r 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 invoke MkGDqcQc MkGDqcQc stop
+$ br app Tomcat ent TomcatServer:Wx7r stop
{% endhighlight %}
-Some effectors require parameters for their invocation, as in the example of "deploy" above. A description of the effector parameters can be obtained using "show effector --params", for example
+Some effectors require parameters for their invocation, as in the example of "deploy" above.
{% highlight bash %}
-$ br show effector --params MkGDqcQc SjJ6TDsR deploy
-Name Type Description Default Value
-url java.lang.String URL of WAR file null
-targetName java.lang.String context path where WAR should be deployed (/ for ROOT) null
+br app Tomcat ent TomcatServer:Wx7r effector deploy
+Name Description Parameters
+deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
{% endhighlight %}
-Now the effector can be invoked by supplying the parameters [NOTE, syntax of how to supply the parameters will be
-dependent on the capabilities of the underlying CLI library, so this is just a guess for now]
+Now the effector can be invoked by supplying the parameters using ```--param parm=value``` or just ```-P parm=value```.
+
+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.
{% highlight bash %}
-$ br invoke MkGDqcQc SjJ6TDsR deploy --url https://tomcat.apache.org/tomcat-6.0-doc/appdev/sample/sample.war --targetName /sample
+$ br app Tomcat ent TomcatServer:Wx7r 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:Wx7r sensor webapp.url | tr -d '"')
+$ curl $webapp/sample/
+<html>
+<head>
+<title>Sample "Hello, World" Application</title>
+</head>
+# etc. etc.
{% endhighlight %}
## Activities
+The 'activity' command allows us to investigate the activities of an entity.
+
+To view a list of all activities associated with an entity simply use
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r activity
+Id Task Submitted Status Streams
+LtD5P1cb start Thu Dec 17 15:04:43 GMT 2015 Completed
+l2qo4vTl provisioning (FixedListMachineProvisi... Thu Dec 17 15:04:43 GMT 2015 Completed
+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.
+{% endhighlight %}
+
+To view the details of an individual activity provide its ID:
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r activity jwwcJWmF
+Id: jwwcJWmF
+DisplayName: start (processes)
+Description:
+EntityId: efUvVWAw
+EntityDisplayName: TomcatServer:efUv
+Submitted: Thu Dec 17 15:04:43 GMT 2015
+Started: Thu Dec 17 15:04:43 GMT 2015
+Ended: Thu Dec 17 15:08:59 GMT 2015
+CurrentStatus: Completed
+IsError: false
+IsCancelled: false
+SubmittedByTask: LtD5P1cb
+Streams:
+DetailedStatus: "Completed after 4m 16s
+
+No return value (null)"
+{% endhighlight %}
+
+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:
+
+{% highlight bash %}
+$ br app Tomcat ent TomcatServer:Wx7r activity -c jwwcJWmF
+Id Task Submitted Status
+UpYRc3fw copy-pre-install-resources Thu Dec 17 15:04:43 GMT 2015 Completed
+ig8sBHQr pre-install Thu Dec 17 15:04:43 GMT 2015 Completed
+Elp4HaVj pre-install-command Thu Dec 17 15:04:43 GMT 2015 Completed
+YOvNobJk setup Thu Dec 17 15:04:43 GMT 2015 Completed
+VN3cDKki copy-install-resources Thu Dec 17 15:08:43 GMT 2015 Completed
+xDJXQC0J install Thu Dec 17 15:08:43 GMT 2015 Completed
+zxMDXUxz post-install-command Thu Dec 17 15:08:58 GMT 2015 Completed
+qnQnw7Oc customize Thu Dec 17 15:08:58 GMT 2015 Completed
+ug044ArS copy-runtime-resources Thu Dec 17 15:08:58 GMT 2015 Completed
+STavcRc8 pre-launch-command Thu Dec 17 15:08:58 GMT 2015 Completed
+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
+{% endhighlight %}
+
+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:Wx7r act KLTxDkoa stdout
+BASE_DIR_RESULT:/home/vagrant/brooklyn-managed-processes:BASE_DIR_RESULT
+
+{% endhighlight %}
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/36e2f14a/docs/guide/start/policies-cli.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/policies-cli.md b/docs/guide/start/policies-cli.md
index 10318fe..2839bba 100644
--- a/docs/guide/start/policies-cli.md
+++ b/docs/guide/start/policies-cli.md
@@ -2,6 +2,7 @@
title: Getting Started - Policies
title_in_menu: Policies
layout: website-normal
+menu-parent: index-cli.md
---