Monitoring and Managing Applications
So far we have gone through Cloudsoft AMP’s ability to deploy an application blueprint to a location, but this is 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 application Id Name Status Location tqxd5eqdps Tomcat RUNNING
application can be shortened to the alias app, for example:
$ br app Id Name Status Location tqxd5eqdps Tomcat RUNNING
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.
Note that in TOSCA, Location is blank since default.tosca.location is used by default.
Things we might want to do
Get the application details
Using the name `Tomcat` we can get the application details:
$ br application TomcatId: tqxd5eqdps Name: Tomcat Status: RUNNING ServiceUp: true Type: org.apache.brooklyn.entity.stock.BasicApplication CatalogItemId:
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
|- tomcat
+- io.cloudsoft.brooklyn.tosca13.entities.ToscaSoftwareComponentNodeEntity
|- tosca.nodes.Abstract.Compute
+- io.cloudsoft.brooklyn.tosca13.entities.ToscaComputeNodeEntity
View our application's blueprint
You can view the blueprint for the application again:
$ br application Tomcat spec
name: Tomcat
extra.tosca.metadata:
tosca_definitions_version: tosca_simple_yaml_1_3
location: tosca.default.location
metadata:
template_version: 1.0.0-SNAPSHOT
brooklyn.initializers:
- type: brooklyn.tosca.application
services:
- id: tomcat
type: tosca-tomcat9-node
brooklyn.config:
artifacts:
ROOT_war:
file: classpath://io.cloudsoft.brooklyn.tosca13.tosca-3-tier:resources/tosca-hello-world-sql-webapp.war
View our application's configuration
You can view the configuration of the application:
$ br application Tomcat configKey Value camp.template.id AUUJwQj2 brooklyn.wrapper_app true
Having created the application, we can find a summary of all deployed applications using:
$ br application Id Name Status Location hTPAF19s Tomcat RUNNING ajVVAhER
application can be shortened to the alias app, for example:
$ br app Id 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 specname: Tomcat version: 1.0.0-SNAPSHOT services: - type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer name: tomcatServer location: ...
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 Cloudsoft AMP’s representation of a software package or service which it can control or interact with.
To list the entities of the application you can use the entity or ent command:
$ br application Tomcat entityId Name Type lqbw1bse1x tomcat io.cloudsoft.brooklyn.tosca13.entities.ToscaSoftwareComponentNodeEntity
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 tomcatId: lqbw1bse1x Name: tomcat Status: RUNNING ServiceUp: true Type: io.cloudsoft.brooklyn.tosca13.entities.ToscaSoftwareComponentNodeEntity CatalogItemId: tosca-tomcat9-node:1.0.0-SNAPSHOT
Also you can see the configuration of this entity with the config command.
$ br application Tomcat entity tomcat configKey Value camp.plan.id tomcat tosca.requirements [map[host:map[capability:tosca.capabilities.Compute description:node:map[value:tosca.nodes.Compute] occurrences:[0 1] relationship:map[brooklynRelationshipType: copy: description: id: metadata: relationshipTemplateReference:tosca.relationships.HostedOn valid_target_types: version: ]]]] camp.template.id sOhvqjn7 defaultDisplayName tosca.nodes.SoftwareComponent artifacts.ROOT_war map[file:classpath://io.cloudsoft.brooklyn.tosca13.tosca-3-tier:resources/tosca-hello-world-sql-webapp.war type:tosca.artifacts.File] </pre>
An Entity is Cloudsoft AMP’s representation of a software package or service which it can control or interact with.
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 available (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 @ 1720706656917 / Thu Jul 11 15:04:16 BST 2024
# etc.
To explore sensors on a specific entity use the sensor command with an entity specified:
$ br application Tomcat entity tomcat sensor
Name Description Value
entity.id entity.id lqbw1bse1x
health.uri http://13.53.33.193:8080/health/index.html
host.type Description of the purpose of this node Application Server
main.uri http://13.53.33.193:8080
service.isUp Whether the service is active and available (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
# etc.
To display the value of a selected sensor, give the command the sensor name as an argument
$ br application Tomcat entity tomcat sensor health.uri http://13.53.33.193:8080/health/index.html
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"
# etc.
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.
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 delete Forcibly delete, not invoking stop, not waiting on dependents, and passing cloudsoft.delete.force to operations force 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, restart and delete, are common to all applications and software process entities in AMP TOSCA.
You can list the effectors for a specific entity using the command:
$ br application Tomcat entity tomcat effectorName Description Parameters Standard.configure Standard.create TOMCAT_gz Standard.restart Standard.start Standard.stop delete Delete the entity and typically the underlying resources it represents force 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
To view the details for a specific effector, append its name to the command:
$ br application Tomcat entity tomcat effector restartName Description Parameters restart Restart the process/service represented by an entity
These effectors can also be invoked by appending invoke to this command.
Some effectors require parameters for their invocation which can be supplied using --param parm=value.
The commands below trigger a restart of the Apache Tomcat hello world example to our Tomcat Server.
Then, we use the health uri to check the health of the Tomcat server. Note that in some cloud locations (such as AWS), it
might be required to explicitly open the port to be able to call the server.
$ br application Tomcat entity tomcat effector Standard.restart invoke
$ webapp_health=$(br application Tomcat entity tomcatServer sensor health.uri)
$ curl $webapp_healthtrue
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 AMP.
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 its 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 -param url=https://tomcat.apache.org/tomcat-6.0-doc/appdev/sample/sample.war -param targetName=sample
$ webapp=$(br application Tomcat entity tomcatServer sensor webapp.url | tr -d '"')
$ curl $webapp/sample/Activities
Activities are the actions an application or entity takes within Cloudsoft AMP. 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 tomcat activityId Task Submitted Status Streams I9lTYZcD start Fri Jul 12 13:31:53 BST 2024 Completed bo7VZSZn publish outputs as sensors Fri Jul 12 13:34:06 BST 2024 Completed Vls6WBXA gathering output Fri Jul 12 13:34:05 BST 2024 Completed env,stderr,stdin,stdout ...
To view the details of an individual activity, add its ID to the command. In our case this is jwwcJWmF
$ br application Tomcat entity tomcat activity I9lTYZcD
Id: | I9lTYZcD
DisplayName: | start
Description: | Invoking effector start on tomcat with parameters {locations=[]}
EntityId: | lc6s64o7gq
EntityDisplayName: | tomcat
Submitted: | Fri Jul 12 13:31:53 BST 2024
Started: | Fri Jul 12 13:31:53 BST 2024
Ended: | Fri Jul 12 13:34:06 BST 2024
CurrentStatus: | Completed
IsError: | false
IsCancelled: | false
SubmittedByTask: | pDEw0nMl
Streams: |
DetailedStatus: | "Completed after 2m 12s 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 tomcat act Vls6WBXA stdoutOLDPWD=/home/users/amp/.brooklyn-tosca-execution/r90sdoobla/lc6s64o7gq/20240712-133402748-Standard.start
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 tomcat 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 tomcat act ka0eoZL4 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 Tomcat entity tomcat activity ka0eoZL4
Id: ka0eoZL4
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 tomcat activity --children I9lTYZcDId Task Submitted Status Streams c8ddu9Jo publish state sensors: STARTED Fri Jul 12 13:34:06 BST 2024 Completed dzV0GPWP Standard.start Fri Jul 12 13:34:02 BST 2024 Completed XB2exwBz publish state sensors: STARTING Fri Jul 12 13:34:02 BST 2024 Completed BCyCxGd2 Standard.configure Fri Jul 12 13:33:48 BST 2024 Completed ul5NU4ak publish state sensors: CONFIGURED Fri Jul 12 13:34:02 BST 2024 Completed gfFOot6G publish state sensors: CREATED Fri Jul 12 13:33:48 BST 2024 Completed lQRKEA7F publish state sensors: CONFIGURING Fri Jul 12 13:33:48 BST 2024 Completed dwHNHQ7t Standard.create Fri Jul 12 13:33:15 BST 2024 Completed Iuy6S7Np waiting on service.isUp Fri Jul 12 13:33:15 BST 2024 Completed MbnAaFFQ start Fri Jul 12 13:31:53 BST 2024 Completed zHOgWOLK publish state sensors: CREATING Fri Jul 12 13:31:53 BST 2024 Completed
Activities are the actions an application or entity takes within Cloudsoft AMP. 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