brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [07/13] incubator-brooklyn git commit: docs: separate “launching” and “runtime management”
Date Mon, 19 Jan 2015 23:00:27 GMT
docs: separate “launching” and “runtime management”

Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/aed2f1c8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/aed2f1c8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/aed2f1c8

Branch: refs/heads/master
Commit: aed2f1c8ae96e44d9a65ee8e994a28e494794a35
Parents: 663f673
Author: Aled Sage <aled.sage@gmail.com>
Authored: Thu Jan 15 16:51:22 2015 +0000
Committer: Aled Sage <aled.sage@gmail.com>
Committed: Thu Jan 15 16:51:22 2015 +0000

----------------------------------------------------------------------
 docs/guide/ops/index.md                         |   3 +-
 docs/guide/ops/launching/index.md               |  87 ++++
 docs/guide/ops/runtime-management/index.md      | 324 +++++++++++++++
 .../webconsole-dashboard-w400.png               | Bin 0 -> 137463 bytes
 .../runtime-management/webconsole-dashboard.png | Bin 0 -> 214723 bytes
 .../webconsole-detail-w400.png                  | Bin 0 -> 111993 bytes
 .../runtime-management/webconsole-detail.png    | Bin 0 -> 165359 bytes
 docs/guide/ops/webconsole/index.md              | 399 -------------------
 .../webconsole/webconsole-dashboard-w400.png    | Bin 137463 -> 0 bytes
 .../ops/webconsole/webconsole-dashboard.png     | Bin 214723 -> 0 bytes
 .../ops/webconsole/webconsole-detail-w400.png   | Bin 111993 -> 0 bytes
 docs/guide/ops/webconsole/webconsole-detail.png | Bin 165359 -> 0 bytes
 12 files changed, 413 insertions(+), 400 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md
index 27da59f..2e076da 100644
--- a/docs/guide/ops/index.md
+++ b/docs/guide/ops/index.md
@@ -5,7 +5,8 @@ children:
 - locations/index.md
 - locations/configuring.md
 - persistence/
-- webconsole/
+- launching/
+- runtime-management/
 ---
 
 {% include list-children.html %}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/launching/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/launching/index.md b/docs/guide/ops/launching/index.md
new file mode 100644
index 0000000..8eb3dd9
--- /dev/null
+++ b/docs/guide/ops/launching/index.md
@@ -0,0 +1,87 @@
+---
+title: Launching Brooklyn
+layout: website-normal
+---
+
+There are several ways to launch applications with brooklyn, and useful configuration options,
+as well as a debug-view web console.
+
+This chapter describes how to launch brooklyn.
+
+
+Startup Configuration
+---------------------
+
+brooklyn can read configuration from a variety of places:
+
+* the file ``~/.brooklyn/brooklyn.properties``
+* ``-D`` defines on the brooklyn (java) command-line
+* shell environment variables
+
+Default properties are described in the Javadoc and code of the class ``BrooklynProperties``,
+but some of the most common ones are:
+ 
+{% highlight properties %}
+brooklyn.location.jclouds.aws-ec2.identity=AKA50M30N3S1DFR0MAW55
+brooklyn.location.jclouds.aws-ec2.credential=aT0Ps3cr3tC0D3wh1chAW5w1llG1V3y0uTOus333
+brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/path/to/id_rsa       # use specified key
(default is ~/.ssh/id_rsa)
+brooklyn.location.jclouds.aws-ec2.publicKeyFile=~/path/to/id_rsa.pub    # (optional, inferred
from previous if omitted)
+{% endhighlight %} 
+
+These can be specified as a shell environment variable or as a Java system property,
+although in those contexts the conventional format ``BROOKLYN_JCLOUDS_AWS_EC2_IDENTITY``

+is supported and recommended.
+
+
+Command Line Interface
+----------------------
+
+Brooklyn comes with a Command Line Interface (cli) that makes it easier to launch an application.
+
+In order to have easy access to the cli it is useful to configure the PATH environment variable
to also point to the cli's bin directory:
+
+{% highlight bash %}
+BROOKLYN_HOME=/path/to/brooklyn/
+export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/
+{% endhighlight %}
+
+If you have set this up correctly you should be able to invoke the ```brooklyn``` command:
+
+{% highlight bash %}
+brooklyn
+{% endhighlight %}
+
+To get information about all the supported cli options just run:
+
+{% highlight bash %}
+brooklyn help
+usage: brooklyn [(-q | --quiet)] [(-v | --verbose)] <command> [<args>]
+
+The most commonly used brooklyn commands are:
+    help     Display help information about brooklyn
+    info     Display information about brooklyn
+    launch   Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable
needs to be set up beforehand to point to the user application classpath.
+
+See 'brooklyn help <command>' for more information on a specific command.
+{% endhighlight %}
+
+Here is an example of the commands you might run to get the Brooklyn code, compile it and
launch an application:
+
+{% highlight bash %}
+git clone https://github.com/apache/incubator-brooklyn.git
+cd brooklyn
+mvn clean install -DskipTests
+BROOKLYN_HOME=$(pwd)
+export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/
+export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes
+brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost
+{% endhighlight %}
+
+You can add things to the brooklyn classpath in a number of ways:
+
+* Add ``.jar`` files to brooklyn's ``./lib/dropins/`` directory. These are added at the end
of the classpath.
+* Add ``.jar`` files to brooklyn's ``./lib/patch/`` directory. These are added at the front
of the classpath.
+* Add resources to brooklyn's ``./conf/`` directory. This directory is at the very front
of the classpath.
+* Use the ``BROOKLYN_CLASSPATH`` environment variable. If set, this is prepended to the brooklyn
classpath.
+
+

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/index.md b/docs/guide/ops/runtime-management/index.md
new file mode 100644
index 0000000..42b274e
--- /dev/null
+++ b/docs/guide/ops/runtime-management/index.md
@@ -0,0 +1,324 @@
+---
+title: Runtime Management
+layout: website-normal
+---
+
+brooklyn uses many of the ideas from autonomic computing to implement management of entities
in a 
+structured and reusable fashion (including provisioning, healing, and optimising).
+
+Each external system, process or service is represented as an entity within brooklyn, with

+collections of these being represented and managed by other entities, and so forth through

+a hierarchy rooted in entities referred to as "Applications". Each entity has:
+
+- provisioning and tear-down logic for the external system(s) it represents
+- sensors which it publishes to report on its state and activity
+- effectors which can be invoked to change it
+- policies which perform analysis, enrichment (sensors), and execution (effectors). It is
the 
+  policies in brooklyn which perform the self-management (in autonomic terms) by monitoring
sensors 
+  and invoking effectors.
+
+This chapter describes these high-level runtime concepts, as well as presenting more
+detailed information on the underlying implementation of management within brooklyn.
+
+
+
+
+Management Web Console
+----------------------
+
+The web-based management console that comes with brooklyn serves as a way to observe and
manage brooklyn entities.
+It provides low-level details of activity (including stack-traces), sensor values, and policies,
+and some visual widgets for observing what is happening.
+This console is not designed as a management dashboard or portal -- 
+many good options exist in that space --
+but what could be useful is to embed widgets from the brooklyn portal for selected high-level
views.
+
+<!-- FIXME Update to use new construction pattern, rather than calling app's constructor
-->
+To start a management console from your own code, use ``BrooklynLaucher.launch``:
+{% highlight java %}
+public static void main(String[] argv) {
+	Application app = new MyApplicationExample(displayName:"myapp")
+    BrooklynServerDetails server = BrooklynLauncher.newLauncher()
+            .managing(app)
+            .launch();
+	// ...
+}
+{% endhighlight %}
+
+This will start an embedded brooklyn management node, including the web console.
+The URL for the web console defaults to http://127.0.0.1:8081, .
+
+The mechanism for launching brooklyn management will change in a future release. For this
release, the brooklyn management node is embedded.
+
+The console contains two main views: Dashboard and Detail. These update in real-time.
+
+**Dashboard**
+
+The dashboard is a high level overview of the state of the application:
+
+[![Screenshot of the Webconsole Dashboard](webconsole-dashboard-w400.png "Screenshot of the
Webconsole Dashboard")](webconsole-dashboard.png)
+
+
+**Detail**
+
+The Detail view gives an in-depth view of the application and its entities. 
+Child-parent relationships between entities are navigable using the entity tree;
+each entity is shown with its children (or, in the case of childless group entities, the
members). 
+Selecting a specific entity allows you to access detailed information about that entity.
+
+[![Screenshot of the Webconsole Detail](webconsole-detail-w400.png "Screenshot of the Webconsole
Detail")](webconsole-detail.png)
+
+The Detail view contains a breadcrumb trail, showing the current entitiy's position in the
heirarchy, and six tabs:
+
+**Summary:** Description of the selected entity.
+
+**Sensors:** Lists the attribute sensors that the entity has and their values.
+
+**Effectors:** Lists the effectors that can be invoked on the selected entity.
+
+**Activity:** Current and historic activity of the entity, currently running effectors, finished
effectors.
+
+**Location:** The geographical location of the selected entity.
+
+**Policies:** Lists the policies associated with the current entity. Policies can be suspended,
resumed and removed through the UI.
+
+### Security
+
+Security providers can be configured by specifying `brooklyn.webconsole.security.provider`
equal 
+to the name of a class implementing `SecurityProvider`.
+An implementation of this could point to Spring, LDAP, OpenID or another identity management
system.
+
+The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and
passwords
+which should be specified as configuration parameters e.g. in `brooklyn.properties`.
+This configuration could look like:
+
+{% highlight properties %}
+brooklyn.webconsole.security.users=admin
+brooklyn.webconsole.security.user.admin.salt=OHDf
+brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
+{% endhighlight %}
+
+The `users` line should contain a comma-separated list. The special value `*` is accepted
to permit all users.
+
+To generate this, the brooklyn CLI can be used:
+{% highlight bash %}
+brooklyn generate-password --user admin
+
+Enter password: 
+Re-enter password: 
+
+Please add the following to your brooklyn.properies:
+
+brooklyn.webconsole.security.users=admin
+brooklyn.webconsole.security.user.admin.salt=OHDf
+brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
+{% endhighlight %}
+
+For legacy and dev purposes, the password can also be stored in plain text:
+
+{% highlight properties %}
+brooklyn.webconsole.security.users=admin
+brooklyn.webconsole.security.user.admin.password=mypassword
+{% endhighlight %}
+
+If not using the web console, you can specify
+`brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.BlackholeSecurityProvider`
to prevent inadvertant logins.
+During dev/test you can specify `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.AnyoneSecurityProvider`
+to allow logins with no credentials. 
+
+To enable https, you will need a server certificate in a java keystore. To create a self-signed
certificate, you can use the
+following command:
+
+`keytool -genkey -keyalg RSA -alias brooklyn -keystore <path-to-keystore-directory>/server.key
-storepass mypassword -validity 360 -keysize 2048`
+
+You will then be prompted to enter you name and organization details. This will create a
keystore with the password `mypassword`
+- you should use your own secure password, which will be the same password used in your brooklyn.properties
(below). 
+You will also need to replace `<path-to-keystore-directory>` with the full path of
the folder where you wish to store your
+keystore. 
+
+The certificate generated will be a self-signed certificate and will not have a CN field
identifying the website server 
+name, which will cause a warning to be displayed by the browser when viewing the page. For
production servers, a valid signed 
+certificate from a trusted certifying authority should be used instead
+
+To enable HTTPS in Brooklyn, add the following to your brooklyn.properties:
+
+```
+# HTTPS
+brooklyn.webconsole.security.https.required=true
+brooklyn.webconsole.security.keystore.url=<path-to-keystore-directory>/server.key
+brooklyn.webconsole.security.keystore.password=mypassword
+brooklyn.webconsole.security.keystore.certificate.alias=brooklyn
+```
+
+In order to access the Brooklyn console, you will also need to enable security, and setup
a user as described above
+
+Other Ways to Observe Activity
+------------------------------
+
+### Java API
+
+``ManagementContext`` provides a Java programmatic API. 
+
+More information can be found in the javadoc for ``ManagementContext``.
+
+### Command-line Console
+
+*Not available yet.*
+
+### Management REST API
+
+Brooklyn does not yet expose a REST API. This was to allow the APi to be designed to align
with emerging standards.
+
+Selected management operations are possible remotely using links exposed by the GUI (after
authenticating with the GUI).
+
+### Logging
+
+Brooklyn uses the SLF4J logging facade,  which allows use of many popular frameworks including
java.util.logging, log4j, and logback.
+
+The convention for log levels is as follows:
+* ERROR and above:  exceptional situations which indicate that something has unexpectedly
failed or
+some other problem has occured which the user is expected to attend to
+* WARN:  exceptional situations which the user may which to know about but which do not necessarily
indicate failure or require a response
+* INFO:  a synopsis of activity, but which should not generate large volumes of events nor
overwhelm a human observer
+* DEBUG and lower:  detail of activity which is not normally of interest, but which might
merit closer inspection under certain circumstances.
+
+Loggers follow the ``package.ClassName`` naming standard.  
+
+It is possible for entities to emit logging activity sensors so that an operator can observe
what is occurring within their application through the web console or via programmatic means.
+
+Examples for testing can be found in some of the poms.
+
+
+<!---
+
+<a name="distributed-management"></a>
+Distributed Management
+----------------------
+
+TODO Describe how and when objects become "live", pushed out to other nodes.
+-->
+
+<!---
+
+<a name="resilience"></a>
+Resilience
+----------
+TODO
+*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code)
the docs and lend a hand.*
+-->
+
+
+Key APIs
+--------
+<!---
+TODO - brief overview of key APIs
+-->
+*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code)
the docs and lend a hand.*
+
+- ``ManagementContext`` (Java management API)
+- ``EntityLocal`` (used by policies)
+
+
+<!---
+TODO - describe how to simply configure logging slf4j
+-->
+
+Sensors and Effectors
+---------------------
+
+### Sensors
+
+Sensors are typically defined as static named fields on the Entity subclass. These define
the channels of events and activity that interested parties can track remotely. For example:
+{% highlight java %}
+/** a sensor for saying hi (illustrative), carrying a String value 
+	which is typically the name of the person to whom we are saying hi */
+public static final Sensor<String> HELLO_SENSOR = ...
+
+{% endhighlight %}
+
+If the entity is local (e.g. to a policy) these can be looked up using ``get(Sensor)``. If
it may be remote, you can subscribe to it through various APIs.
+
+<!---
+TODO probably say about events now, quick reference about SubscriptionManager (either here
or in next section on management context)
+TODO remaining section on Sensors perhaps should be moved to Writing Entities section? as
reader won't need to know too much detail of sensor types to understand policies... though
perhaps saying some is right. (Talking about JSON is almost certainly overkill...)
+-->
+
+Sensors are used by operators and policies to monitor health and know when to invoke the
effectors. The sensor data forms a nested map (i.e. JSON), which can be subscribed to through
the ``ManagementContext``.
+
+Often ``Policy`` instances will subscribe to sensor events on their associated entity or
its children; these events might be an ``AttributeValueEvent`` – an attribute value being
reported on change or periodically – or something transient such as ``LogMessage`` or a
custom ``Event`` such as "TOO_HOT".
+
+<!---
+TODO check classes above; is this much detail needed here?
+-->
+
+Sensor values form a map-of-maps. An example of some simple sensor information is shown below
in JSON:
+		
+	{
+	  config : {
+		url : "jdbc:mysql://ec2-50-17-19-65.compute-1.amazonaws.com:3306/mysql"
+		status : "running"
+	  }
+	  workrate : {
+		msgsPerSec : 432
+	  }
+	}
+
+Sensor values are defined as statics, which can be used to programmatically drive the subscription.
+<!---
+TODO , etc., example
+-->
+
+### SubscriptionManager
+
+*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs
and lend a hand.*
+
+*See the* ``SubscriptionManager`` *class.*
+<!---
+TODO
+-->
+
+### Effectors
+
+Like sensors and config info, effectors are also static fields on the Entity class. These
describe actions available on the entity, similar to methods. Their implementation includes
details of how to invoke them, typically this is done by calling a method on the entity. Effectors
are typically defined as follows:
+
+{% highlight java %}
+/** an effector which returns no value,
+	but which causes the entity to emit a HELLO sensor event */
+public static Effector<Void> SAY_HI = ...
+
+{% endhighlight %}
+
+Effectors are invoked by calling ``invoke(SAY_HI, name:"Bob")`` or similar. The method may
take an entity if context is not clear, and it takes parameters as named parameters or a Map.
+
+Invocation returns a ``Task`` object (extending ``Future``). This allows the caller to understand
progress and errors on the task, as well as ``Task.get()`` the return value. Be aware that
``task.get()`` is a blocking function that will wait until a value is available before returning.
+
+The management framework ensures that execution occurs on the machine where the ``Entity``
is mastered, with progress, result, and/or any errors reported back to the caller. It does
this through the ``ExecutionManager`` which, where necessary, creates proxy ``Task`` instances.
The ``ExecutionManager`` associates ``Tasks`` with the corresponding ``Entity`` so that these
can be tracked externally (and relocated if the Entity is remastered to a different location).
+
+It is worth noting that where a method corresponds to an effector, direct invocation of that
method on an ``Entity`` will implicitly generate the ``Task`` object as though the effector
had been invoked. For example, invoking ``Cluster.resize(int)``, where ``resize`` provides
an ``Effector RESIZE``, will generate a ``Task`` which can be observed remotely.
+
+### ExecutionManager
+
+The ``ExecutionManager`` is responsible for tracking simultaneous executing tasks and associating
these with given **tags**.
+Arbitrary tasks can be run by calling ``Task submit(Runnable)`` (similarly to the standard
``Executor``, although it also supports ``Callable`` arguments including Groovy closures,
and can even be passed ``Task`` instances which have not been started). ``submit`` also accepts
a few other named parameters, including ``description``, which allow additional metadata to
be kept on the ``Task``. The main benefit then is to have rich metadata for executing tasks,
which can be inspected through methods on the ``Task`` interface.
+
+By using the ``tag`` or ``tags`` named parameters on ``submit`` (or setting ``tags`` in a
``Task`` that is submitted), execution can be associated with various categories. This allows
easy viewing can be examined by calling
+``ExecutionManager.getTasksWithTag(...)``.
+
+The following example uses Groovy, with time delays abused for readability. brooklyn's test
cases check this using mutexes, which is recommended.
+	
+	ExecutionManager em = []
+	em.submit(tag:"a", description:"One Mississippi", { Thread.sleep(1000) })
+	em.submit(tags:["a","b"], description:"Two Mississippi", { Thread.sleep(1000) })
+	assert em.getTasksWithTag("a").size()==2
+	assert em.getTasksWithTag("a").every { Task t -> !t.isDone() }
+	Thread.sleep(1500)
+	assert em.getTasksWithTag("a").size()==2
+	assert em.getTasksWithTag("a").every { Task t -> t.isDone() }
+
+It is possible to define ParallelTasks and SequentialTasks and to specify inter-task relationships
with TaskPreprocessors. This allows building quite sophisticated workflows relatively easily.

+
+Continuing the example above, submitting a SequentialTasks or specifying ``em.setTaskPreprocessorForTag("a",
SingleThreadedExecution.class)`` will cause ``Two Mississippi`` to run after ``One Mississippi``
completes.
+
+For more information consult the javadoc on these classes and associated tests.
+
+Note that it is currently necessary to prune dead tasks, either periodically or by the caller.
By default they are kept around for reference. It is expected that an enhancement in a future
release will allow pruning completed and failed tasks after a specified amount of time.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png b/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png
new file mode 100644
index 0000000..6364dc5
Binary files /dev/null and b/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png
differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/webconsole-dashboard.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/webconsole-dashboard.png b/docs/guide/ops/runtime-management/webconsole-dashboard.png
new file mode 100644
index 0000000..cac5567
Binary files /dev/null and b/docs/guide/ops/runtime-management/webconsole-dashboard.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/webconsole-detail-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/webconsole-detail-w400.png b/docs/guide/ops/runtime-management/webconsole-detail-w400.png
new file mode 100644
index 0000000..b372e55
Binary files /dev/null and b/docs/guide/ops/runtime-management/webconsole-detail-w400.png
differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/runtime-management/webconsole-detail.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/webconsole-detail.png b/docs/guide/ops/runtime-management/webconsole-detail.png
new file mode 100644
index 0000000..17829cd
Binary files /dev/null and b/docs/guide/ops/runtime-management/webconsole-detail.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/index.md b/docs/guide/ops/webconsole/index.md
deleted file mode 100644
index 62afc2c..0000000
--- a/docs/guide/ops/webconsole/index.md
+++ /dev/null
@@ -1,399 +0,0 @@
----
-title: Runtime Management
-layout: website-normal
----
-
-brooklyn uses many of the ideas from autonomic computing to implement management of entities
in a structured and reusable fashion (including provisioning, 
-healing, and optimising).
-
-Each external system, process or service is represented as an entity within brooklyn, with
collections of these being represented and
-managed by other entities, and so forth through a hierarchy rooted in entities referred to
as "Applications". Each entity has:
-
-- provisioning and tear-down logic for the external system(s) it represents
-- sensors which it publishes to report on its state and activity
-- effectors which can be invoked to change it
-- policies which perform analysis, enrichment (sensors), and execution (effectors). It is
the policies in brooklyn which
-  perform the self-management (in autonomic terms) by monitoring sensors and invoking effectors.
-
-There are several ways to launch applications with brooklyn, and useful configuration options,
-as well as a debug-view web console.
-This chapter describes these high-level runtime concepts, then proceeds to present more
-detailed information on the underlying implementation of management within brooklyn.
-
-
-Startup Configuration
----------------------
-
-brooklyn can read configuration from a variety of places:
-
-* the file ``~/.brooklyn/brooklyn.properties``
-* ``-D`` defines on the brooklyn (java) command-line
-* shell environment variables
-
-Default properties are described in the Javadoc and code of the class ``BrooklynProperties``,
-but some of the most common ones are:
- 
-{% highlight properties %}
-brooklyn.location.jclouds.aws-ec2.identity=AKA50M30N3S1DFR0MAW55
-brooklyn.location.jclouds.aws-ec2.credential=aT0Ps3cr3tC0D3wh1chAW5w1llG1V3y0uTOus333
-brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/path/to/id_rsa       # use specified key
(default is ~/.ssh/id_rsa)
-brooklyn.location.jclouds.aws-ec2.publicKeyFile=~/path/to/id_rsa.pub    # (optional, inferred
from previous if omitted)
-{% endhighlight %} 
-
-These can be specified as a shell environment variable or as a Java system property,
-although in those contexts the conventional format ``BROOKLYN_JCLOUDS_AWS_EC2_IDENTITY``

-is supported and recommended. 
-
-
-
-Command Line Interface
-----------------------
-
-Brooklyn comes with a Command Line Interface (cli) that makes it easier to launch an application.
-
-In order to have easy access to the cli it is useful to configure the PATH environment variable
to also point to the cli's bin directory:
-
-{% highlight bash %}
-BROOKLYN_HOME=/path/to/brooklyn/
-export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/
-{% endhighlight %}
-
-If you have set this up correctly you should be able to invoke the ```brooklyn``` command:
-
-{% highlight bash %}
-brooklyn
-{% endhighlight %}
-
-To get information about all the supported cli options just run:
-
-{% highlight bash %}
-brooklyn help
-usage: brooklyn [(-q | --quiet)] [(-v | --verbose)] <command> [<args>]
-
-The most commonly used brooklyn commands are:
-    help     Display help information about brooklyn
-    info     Display information about brooklyn
-    launch   Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable
needs to be set up beforehand to point to the user application classpath.
-
-See 'brooklyn help <command>' for more information on a specific command.
-{% endhighlight %}
-
-Here is an example of the commands you might run to get the Brooklyn code, compile it and
launch an application:
-
-{% highlight bash %}
-git clone https://github.com/apache/incubator-brooklyn.git
-cd brooklyn
-mvn clean install -DskipTests
-BROOKLYN_HOME=$(pwd)
-export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/
-export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes
-brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost
-{% endhighlight %}
-
-You can add things to the brooklyn classpath in a number of ways:
-
-* Add ``.jar`` files to brooklyn's ``./lib/dropins/`` directory. These are added at the end
of the classpath.
-* Add ``.jar`` files to brooklyn's ``./lib/patch/`` directory. These are added at the front
of the classpath.
-* Add resources to brooklyn's ``./conf/`` directory. This directory is at the very front
of the classpath.
-* Use the ``BROOKLYN_CLASSPATH`` environment variable. If set, this is prepended to the brooklyn
classpath.
-
-
-Management Web Console
-----------------------
-
-The web-based management console that comes with brooklyn serves as a way to observe and
manage brooklyn entities.
-It provides low-level details of activity (including stack-traces), sensor values, and policies,
-and some visual widgets for observing what is happening.
-This console is not designed as a management dashboard or portal -- 
-many good options exist in that space --
-but what could be useful is to embed widgets from the brooklyn portal for selected high-level
views.
-
-<!-- FIXME Update to use new construction pattern, rather than calling app's constructor
-->
-To start a management console from your own code, use ``BrooklynLaucher.launch``:
-{% highlight java %}
-public static void main(String[] argv) {
-	Application app = new MyApplicationExample(displayName:"myapp")
-    BrooklynServerDetails server = BrooklynLauncher.newLauncher()
-            .managing(app)
-            .launch();
-	// ...
-}
-{% endhighlight %}
-
-This will start an embedded brooklyn management node, including the web console.
-The URL for the web console defaults to http://127.0.0.1:8081, .
-
-The mechanism for launching brooklyn management will change in a future release. For this
release, the brooklyn management node is embedded.
-
-The console contains two main views: Dashboard and Detail. These update in real-time.
-
-**Dashboard**
-
-The dashboard is a high level overview of the state of the application:
-
-[![Screenshot of the Webconsole Dashboard](webconsole-dashboard-w400.png "Screenshot of the
Webconsole Dashboard")](webconsole-dashboard.png)
-
-
-**Detail**
-
-The Detail view gives an in-depth view of the application and its entities. 
-Child-parent relationships between entities are navigable using the entity tree;
-each entity is shown with its children (or, in the case of childless group entities, the
members). 
-Selecting a specific entity allows you to access detailed information about that entity.
-
-[![Screenshot of the Webconsole Detail](webconsole-detail-w400.png "Screenshot of the Webconsole
Detail")](webconsole-detail.png)
-
-The Detail view contains a breadcrumb trail, showing the current entitiy's position in the
heirarchy, and six tabs:
-
-**Summary:** Description of the selected entity.
-
-**Sensors:** Lists the attribute sensors that the entity has and their values.
-
-**Effectors:** Lists the effectors that can be invoked on the selected entity.
-
-**Activity:** Current and historic activity of the entity, currently running effectors, finished
effectors.
-
-**Location:** The geographical location of the selected entity.
-
-**Policies:** Lists the policies associated with the current entity. Policies can be suspended,
resumed and removed through the UI.
-
-### Security
-
-Security providers can be configured by specifying `brooklyn.webconsole.security.provider`
equal 
-to the name of a class implementing `SecurityProvider`.
-An implementation of this could point to Spring, LDAP, OpenID or another identity management
system.
-
-The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and
passwords
-which should be specified as configuration parameters e.g. in `brooklyn.properties`.
-This configuration could look like:
-
-{% highlight properties %}
-brooklyn.webconsole.security.users=admin
-brooklyn.webconsole.security.user.admin.salt=OHDf
-brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
-{% endhighlight %}
-
-The `users` line should contain a comma-separated list. The special value `*` is accepted
to permit all users.
-
-To generate this, the brooklyn CLI can be used:
-{% highlight bash %}
-brooklyn generate-password --user admin
-
-Enter password: 
-Re-enter password: 
-
-Please add the following to your brooklyn.properies:
-
-brooklyn.webconsole.security.users=admin
-brooklyn.webconsole.security.user.admin.salt=OHDf
-brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
-{% endhighlight %}
-
-For legacy and dev purposes, the password can also be stored in plain text:
-
-{% highlight properties %}
-brooklyn.webconsole.security.users=admin
-brooklyn.webconsole.security.user.admin.password=mypassword
-{% endhighlight %}
-
-If not using the web console, you can specify
-`brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.BlackholeSecurityProvider`
to prevent inadvertant logins.
-During dev/test you can specify `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.AnyoneSecurityProvider`
-to allow logins with no credentials. 
-
-To enable https, you will need a server certificate in a java keystore. To create a self-signed
certificate, you can use the
-following command:
-
-`keytool -genkey -keyalg RSA -alias brooklyn -keystore <path-to-keystore-directory>/server.key
-storepass mypassword -validity 360 -keysize 2048`
-
-You will then be prompted to enter you name and organization details. This will create a
keystore with the password `mypassword`
-- you should use your own secure password, which will be the same password used in your brooklyn.properties
(below). 
-You will also need to replace `<path-to-keystore-directory>` with the full path of
the folder where you wish to store your
-keystore. 
-
-The certificate generated will be a self-signed certificate and will not have a CN field
identifying the website server 
-name, which will cause a warning to be displayed by the browser when viewing the page. For
production servers, a valid signed 
-certificate from a trusted certifying authority should be used instead
-
-To enable HTTPS in Brooklyn, add the following to your brooklyn.properties:
-
-```
-# HTTPS
-brooklyn.webconsole.security.https.required=true
-brooklyn.webconsole.security.keystore.url=<path-to-keystore-directory>/server.key
-brooklyn.webconsole.security.keystore.password=mypassword
-brooklyn.webconsole.security.keystore.certificate.alias=brooklyn
-```
-
-In order to access the Brooklyn console, you will also need to enable security, and setup
a user as described above
-
-Other Ways to Observe Activity
-------------------------------
-
-### Java API
-
-``ManagementContext`` provides a Java programmatic API. 
-
-More information can be found in the javadoc for ``ManagementContext``.
-
-### Command-line Console
-
-*Not available yet.*
-
-### Management REST API
-
-Brooklyn does not yet expose a REST API. This was to allow the APi to be designed to align
with emerging standards.
-
-Selected management operations are possible remotely using links exposed by the GUI (after
authenticating with the GUI).
-
-### Logging
-
-Brooklyn uses the SLF4J logging facade,  which allows use of many popular frameworks including
java.util.logging, log4j, and logback.
-
-The convention for log levels is as follows:
-* ERROR and above:  exceptional situations which indicate that something has unexpectedly
failed or
-some other problem has occured which the user is expected to attend to
-* WARN:  exceptional situations which the user may which to know about but which do not necessarily
indicate failure or require a response
-* INFO:  a synopsis of activity, but which should not generate large volumes of events nor
overwhelm a human observer
-* DEBUG and lower:  detail of activity which is not normally of interest, but which might
merit closer inspection under certain circumstances.
-
-Loggers follow the ``package.ClassName`` naming standard.  
-
-It is possible for entities to emit logging activity sensors so that an operator can observe
what is occurring within their application through the web console or via programmatic means.
-
-Examples for testing can be found in some of the poms.
-
-
-<!---
-
-<a name="distributed-management"></a>
-Distributed Management
-----------------------
-
-TODO Describe how and when objects become "live", pushed out to other nodes.
--->
-
-<!---
-
-<a name="resilience"></a>
-Resilience
-----------
-TODO
-*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code)
the docs and lend a hand.*
--->
-
-
-Key APIs
---------
-<!---
-TODO - brief overview of key APIs
--->
-*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code)
the docs and lend a hand.*
-
-- ``ManagementContext`` (Java management API)
-- ``EntityLocal`` (used by policies)
-
-
-<!---
-TODO - describe how to simply configure logging slf4j
--->
-
-Sensors and Effectors
----------------------
-
-### Sensors
-
-Sensors are typically defined as static named fields on the Entity subclass. These define
the channels of events and activity that interested parties can track remotely. For example:
-{% highlight java %}
-/** a sensor for saying hi (illustrative), carrying a String value 
-	which is typically the name of the person to whom we are saying hi */
-public static final Sensor<String> HELLO_SENSOR = ...
-
-{% endhighlight %}
-
-If the entity is local (e.g. to a policy) these can be looked up using ``get(Sensor)``. If
it may be remote, you can subscribe to it through various APIs.
-
-<!---
-TODO probably say about events now, quick reference about SubscriptionManager (either here
or in next section on management context)
-TODO remaining section on Sensors perhaps should be moved to Writing Entities section? as
reader won't need to know too much detail of sensor types to understand policies... though
perhaps saying some is right. (Talking about JSON is almost certainly overkill...)
--->
-
-Sensors are used by operators and policies to monitor health and know when to invoke the
effectors. The sensor data forms a nested map (i.e. JSON), which can be subscribed to through
the ``ManagementContext``.
-
-Often ``Policy`` instances will subscribe to sensor events on their associated entity or
its children; these events might be an ``AttributeValueEvent`` – an attribute value being
reported on change or periodically – or something transient such as ``LogMessage`` or a
custom ``Event`` such as "TOO_HOT".
-
-<!---
-TODO check classes above; is this much detail needed here?
--->
-
-Sensor values form a map-of-maps. An example of some simple sensor information is shown below
in JSON:
-		
-	{
-	  config : {
-		url : "jdbc:mysql://ec2-50-17-19-65.compute-1.amazonaws.com:3306/mysql"
-		status : "running"
-	  }
-	  workrate : {
-		msgsPerSec : 432
-	  }
-	}
-
-Sensor values are defined as statics, which can be used to programmatically drive the subscription.
-<!---
-TODO , etc., example
--->
-
-### SubscriptionManager
-
-*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs
and lend a hand.*
-
-*See the* ``SubscriptionManager`` *class.*
-<!---
-TODO
--->
-
-### Effectors
-
-Like sensors and config info, effectors are also static fields on the Entity class. These
describe actions available on the entity, similar to methods. Their implementation includes
details of how to invoke them, typically this is done by calling a method on the entity. Effectors
are typically defined as follows:
-
-{% highlight java %}
-/** an effector which returns no value,
-	but which causes the entity to emit a HELLO sensor event */
-public static Effector<Void> SAY_HI = ...
-
-{% endhighlight %}
-
-Effectors are invoked by calling ``invoke(SAY_HI, name:"Bob")`` or similar. The method may
take an entity if context is not clear, and it takes parameters as named parameters or a Map.
-
-Invocation returns a ``Task`` object (extending ``Future``). This allows the caller to understand
progress and errors on the task, as well as ``Task.get()`` the return value. Be aware that
``task.get()`` is a blocking function that will wait until a value is available before returning.
-
-The management framework ensures that execution occurs on the machine where the ``Entity``
is mastered, with progress, result, and/or any errors reported back to the caller. It does
this through the ``ExecutionManager`` which, where necessary, creates proxy ``Task`` instances.
The ``ExecutionManager`` associates ``Tasks`` with the corresponding ``Entity`` so that these
can be tracked externally (and relocated if the Entity is remastered to a different location).
-
-It is worth noting that where a method corresponds to an effector, direct invocation of that
method on an ``Entity`` will implicitly generate the ``Task`` object as though the effector
had been invoked. For example, invoking ``Cluster.resize(int)``, where ``resize`` provides
an ``Effector RESIZE``, will generate a ``Task`` which can be observed remotely.
-
-### ExecutionManager
-
-The ``ExecutionManager`` is responsible for tracking simultaneous executing tasks and associating
these with given **tags**.
-Arbitrary tasks can be run by calling ``Task submit(Runnable)`` (similarly to the standard
``Executor``, although it also supports ``Callable`` arguments including Groovy closures,
and can even be passed ``Task`` instances which have not been started). ``submit`` also accepts
a few other named parameters, including ``description``, which allow additional metadata to
be kept on the ``Task``. The main benefit then is to have rich metadata for executing tasks,
which can be inspected through methods on the ``Task`` interface.
-
-By using the ``tag`` or ``tags`` named parameters on ``submit`` (or setting ``tags`` in a
``Task`` that is submitted), execution can be associated with various categories. This allows
easy viewing can be examined by calling
-``ExecutionManager.getTasksWithTag(...)``.
-
-The following example uses Groovy, with time delays abused for readability. brooklyn's test
cases check this using mutexes, which is recommended.
-	
-	ExecutionManager em = []
-	em.submit(tag:"a", description:"One Mississippi", { Thread.sleep(1000) })
-	em.submit(tags:["a","b"], description:"Two Mississippi", { Thread.sleep(1000) })
-	assert em.getTasksWithTag("a").size()==2
-	assert em.getTasksWithTag("a").every { Task t -> !t.isDone() }
-	Thread.sleep(1500)
-	assert em.getTasksWithTag("a").size()==2
-	assert em.getTasksWithTag("a").every { Task t -> t.isDone() }
-
-It is possible to define ParallelTasks and SequentialTasks and to specify inter-task relationships
with TaskPreprocessors. This allows building quite sophisticated workflows relatively easily.

-
-Continuing the example above, submitting a SequentialTasks or specifying ``em.setTaskPreprocessorForTag("a",
SingleThreadedExecution.class)`` will cause ``Two Mississippi`` to run after ``One Mississippi``
completes.
-
-For more information consult the javadoc on these classes and associated tests.
-
-Note that it is currently necessary to prune dead tasks, either periodically or by the caller.
By default they are kept around for reference. It is expected that an enhancement in a future
release will allow pruning completed and failed tasks after a specified amount of time.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/webconsole-dashboard-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-dashboard-w400.png b/docs/guide/ops/webconsole/webconsole-dashboard-w400.png
deleted file mode 100644
index 6364dc5..0000000
Binary files a/docs/guide/ops/webconsole/webconsole-dashboard-w400.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/webconsole-dashboard.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-dashboard.png b/docs/guide/ops/webconsole/webconsole-dashboard.png
deleted file mode 100644
index cac5567..0000000
Binary files a/docs/guide/ops/webconsole/webconsole-dashboard.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/webconsole-detail-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-detail-w400.png b/docs/guide/ops/webconsole/webconsole-detail-w400.png
deleted file mode 100644
index b372e55..0000000
Binary files a/docs/guide/ops/webconsole/webconsole-detail-w400.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/aed2f1c8/docs/guide/ops/webconsole/webconsole-detail.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-detail.png b/docs/guide/ops/webconsole/webconsole-detail.png
deleted file mode 100644
index 17829cd..0000000
Binary files a/docs/guide/ops/webconsole/webconsole-detail.png and /dev/null differ


Mime
View raw message