Monitoring and Managing Applications
So far we have gone through Apache Brooklyn’s ability to deploy an application blueprint to a location, but this just the beginning. Next we will outline how to manage the application that has been deployed.
Applications
Having created the application, we can find a summary of all deployed applications using:
$ br applicationId Name Status Location hTPAF19s Tomcat RUNNING ajVVAhER
application can be shortened to the alias app, for example:
$ br appId Name Status Location hTPAF19s Tomcat RUNNING ajVVAhER
A full list of abbreviations such as this can be found in the CLI reference guide.
In the above example the Id hTPAF19s and the Name Tomcat are shown. You can use either of these handles to monitor and control the application. The Id shown for your application will be different to this but the name should be the same, note that if you are running multiple applications the Name may not be unique.
Things we might want to do
Get the application details
Using the name `Tomcat` we can get the application details:
$ br application TomcatId: 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
Explore the hierarchy of all applications
We can explore the management hierarchy of all applications, which will show us the entities they are composed of.
$ br tree|- Tomcat +- org.apache.brooklyn.entity.stock.BasicApplication |- tomcatServer +- org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
View our application's blueprint
You can view the blueprint for the application again:
$ br application Tomcat spec"name: Tomcat\nlocation:\n mylocation\nservices:\n- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer\n"
View our application's configuration
You can view the configuration of the application:
$ br application Tomcat configKey Value camp.template.id l67i25CM brooklyn.wrapper_app true
Entities
An Entity is Apache Brooklyn’s representation of a software package or service which it can control or interact with. All of the entities Apache Brooklyn can use are listed in the Brooklyn Catalog.
To list the entities of the application you can use the entity or ent command:
$ br application Tomcat entityId Name Type Wx7r1C4e tomcatServer org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
This shows one entity is available: tomcatServer. Note that this is the name we gave the entity in the YAML in Launching from a Blueprint on the previous page.
You can get summary information for this entity by providing its name (or ID).
$ br application Tomcat entity tomcatServerId: Wx7r1C4e Name: tomcatServer Status: RUNNING ServiceUp: true Type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer CatalogItemId: null
Also you can see the configuration of this entity with the config command.
$ br application Tomcat entity tomcatServer configKey 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
Sensors
Sensors are properties which show the state of an entity and provide a real-time picture of an entity within an application.
You can view the sensors available on the application using:
$ br application 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 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"
To explore sensors on a specific entity use the sensor command with an entity specified:
$ br application Tomcat entity tomcatServer 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"
expandedinstall.dir Directory for installed artifacts (e.g. expanded dir after unpacking .tgz) "/home/vagrant/brooklyn-managed-processes/installs/TomcatServer_7.0.65/apache-tomcat-7.0.65"
host.address Host IP address "10.10.10.101"
host.name Host name "10.10.10.101"
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"
# etc. etc.
To display the value of a selected sensor, give the command the sensor name as an argument
$ br application Tomcat entity tomcatServer sensor webapp.url"http://10.10.10.101:8080/"
Effectors
Effectors are a means by which you can manipulate the entities in an application. You can list the available effectors for your application using:
$ br application Tomcat effectorName 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
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:
$ br application Tomcat entity tomcatServer effectorName 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 restart Restart the process/service represented by an entity restartChildren,restartMachine start Start the process/service represented by an entity locations stop Stop the process/service represented by an entity stopProcessMode,stopMachineMode undeploy Undeploys the given context/artifact targetName
To view the details for a specific effector, append it’s name to the command:
$ br application Tomcat entity tomcatServer effector deployName Description Parameters deploy Deploys the given artifact, from a source URL, to a given deployment filename/context url,targetName
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.
These parameters can be supplied using --param parm=value or just -P parm=value.
The commands below deploy the Apache Tomcat hello world example 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.
$ 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/<html>
<head>
<title>Sample "Hello, World" Application</title>
</head>
...
Note that at present a tr command is required in the second line below to strip quotation characters from the returned sensor value.
Activities
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 enter:
$ br application Tomcat entity tomcatServer activityId 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 ...
To view the details of an individual activity, add its ID to the command. In our case this is jwwcJWmF
$ br application Tomcat entity tomcatServer activity jwwcJWmFId: 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)"
Things we might want to do
View Input and Output Streams
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,
$ br application Tomcat entity tomcatServer act KLTxDkoa stdoutBASE_DIR_RESULT:/home/vagrant/brooklyn-managed-processes:BASE_DIR_RESULT
Monitor the progress of an effector
To monitor progress on an application as it deploys, for example, one could use a shell loop:
$ while br application Tomcat entity tomcatServer activity | grep 'In progress' ; do
sleep 1; echo ; date;
doneThis 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:
$ br application Tomcat entity tomcatServer act KLTxDkoa stderrDiagnose a failure
If an activity has failed, the "DetailedStatus" value will help us diagnose what went wrong by showing information about the failure.
$ br application evHUlq0n entity tomcatServer activity lZZ9x662
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)"
Adding the "--children" or "-c" parameter will show the activity's child activities, to allow the hierarchical structure of the activities to be investigated:
$ br application Tomcat entity tomcatServer activity -c jwwcJWmFId 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
Next
We will look next at a slightly more complex example, which will illustrate the capabilities of Brooklyn’s policies mechanism, and how to configure dependencies between application entities.