Merge "listen to 'compute.instance.resize.confirm.end' event"

Closes-Bug: #1728477
Change-Id: I39a2672df842b62177fd0c4dbec7b92b398cfb96

.gitignore

@@ -4,8 +4,7 @@
 *.so
 
 # Packages
-*.egg
-*.egg-info
+*.egg*
 dist
 build
 eggs
@@ -25,6 +24,7 @@ pip-log.txt
 .coverage*
 .tox
 nosetests.xml
+.stestr/
 .testrepository
 .venv
 .idea
@@ -43,9 +43,11 @@ output/*/index.html
 
 # Sphinx
 doc/build
-doc/source/api
+doc/source/api/*
 doc/source/samples
-doc/source/watcher.conf.sample
+doc/source/_static/*.sample
+!doc/source/api/index.rst
+!doc/source/api/v1.rst
 
 # pbr generates these
 AUTHORS
@@ -71,3 +73,6 @@ releasenotes/build
 
 # Desktop Service Store
 *.DS_Store
+
+# Autogenerated sample config file
+etc/watcher/watcher.conf.sample

.gitreview

@@ -2,4 +2,3 @@
 host=review.openstack.org
 port=29418
 project=openstack/watcher.git
-defaultbranch=stable/newton

.stestr.conf

@@ -0,0 +1,4 @@
+[DEFAULT]
+test_path=${OS_TEST_PATH:-./watcher/tests}
+top_dir=./
+

.zuul.yaml

@@ -0,0 +1,39 @@
+- project:
+    name: openstack/watcher
+    check:
+      jobs:
+        - watcher-tempest-multinode
+        - legacy-rally-dsvm-watcher-rally
+
+- job:
+    name: watcher-tempest-base-multinode
+    parent: legacy-dsvm-base-multinode
+    run: playbooks/legacy/watcher-tempest-base-multinode/run.yaml
+    post-run: playbooks/legacy/watcher-tempest-base-multinode/post.yaml
+    timeout: 4200
+    required-projects:
+      - openstack-infra/devstack-gate
+      - openstack/python-openstackclient
+      - openstack/python-watcherclient
+      - openstack/watcher
+      - openstack/watcher-tempest-plugin
+    nodeset: legacy-ubuntu-xenial-2-node
+
+- job:
+    name: watcher-tempest-multinode
+    parent: watcher-tempest-base-multinode
+    voting: false
+
+- job:
+    # This job is used by python-watcherclient repo
+    name: watcherclient-tempest-functional
+    parent: legacy-dsvm-base
+    run: playbooks/legacy/watcherclient-tempest-functional/run.yaml
+    post-run: playbooks/legacy/watcherclient-tempest-functional/post.yaml
+    timeout: 4200
+    required-projects:
+      - openstack-dev/devstack
+      - openstack-infra/devstack-gate
+      - openstack/python-openstackclient
+      - openstack/python-watcherclient
+      - openstack/watcher

CONTRIBUTING.rst

@@ -1,13 +1,13 @@
 If you would like to contribute to the development of OpenStack,
 you must follow the steps in this page:
 
-   http://docs.openstack.org/infra/manual/developers.html
+   https://docs.openstack.org/infra/manual/developers.html
 
 Once those steps have been completed, changes to OpenStack
 should be submitted for review via the Gerrit tool, following
 the workflow documented at:
 
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
+   https://docs.openstack.org/infra/manual/developers.html#development-workflow
 
 Pull requests submitted through GitHub will be ignored.
 

HACKING.rst

@@ -8,4 +8,4 @@
 watcher Style Commandments
 ==========================
 
-Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/
+Read the OpenStack Style Commandments https://docs.openstack.org/developer/hacking/

MANIFEST.in

@@ -1,6 +0,0 @@
-include AUTHORS
-include ChangeLog
-exclude .gitignore
-exclude .gitreview
-
-global-exclude *.pyc

README.rst

@@ -1,3 +1,12 @@
+========================
+Team and repository tags
+========================
+
+.. image:: https://governance.openstack.org/badges/watcher.svg
+    :target: https://governance.openstack.org/reference/tags/index.html
+
+.. Change things from this point on
+
 ..
       Except where otherwise noted, this document is licensed under Creative
       Commons Attribution 3.0 License.  You can view the license at:
@@ -10,15 +19,13 @@ Watcher
 
 OpenStack Watcher provides a flexible and scalable resource optimization
 service for multi-tenant OpenStack-based clouds.
-Watcher provides a complete optimization loop-including everything from a
-metrics receiver, complex event processor and profiler, optimization processor
-and an action plan applier. This provides a robust framework to realize a wide
-range of cloud optimization goals, including the reduction of data center
+Watcher provides a robust framework to realize a wide range of cloud
+optimization goals, including the reduction of data center
 operating costs, increased system performance via intelligent virtual machine
 migration, increased energy efficiency-and more!
 
 * Free software: Apache license
-* Wiki: http://wiki.openstack.org/wiki/Watcher
+* Wiki: https://wiki.openstack.org/wiki/Watcher
 * Source:  https://github.com/openstack/watcher
-* Bugs: http://bugs.launchpad.net/watcher
-* Documentation: http://docs.openstack.org/developer/watcher/
+* Bugs: https://bugs.launchpad.net/watcher
+* Documentation: https://docs.openstack.org/watcher/latest/

devstack/files/apache-watcher-api.template

@@ -0,0 +1,42 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+# This is an example Apache2 configuration file for using the
+# Watcher API through mod_wsgi.  This version assumes you are
+# running devstack to configure the software.
+
+Listen %WATCHER_SERVICE_PORT%
+
+<VirtualHost *:%WATCHER_SERVICE_PORT%>
+    WSGIDaemonProcess watcher-api user=%USER% processes=%APIWORKERS% threads=1 display-name=%{GROUP}
+    WSGIScriptAlias / %WATCHER_WSGI_DIR%/app.wsgi
+    WSGIApplicationGroup %{GLOBAL}
+    WSGIProcessGroup watcher-api
+    WSGIPassAuthorization On
+
+    ErrorLogFormat "%M"
+    ErrorLog /var/log/%APACHE_NAME%/watcher-api.log
+    CustomLog /var/log/%APACHE_NAME%/watcher-api-access.log combined
+
+
+    <Directory %WATCHER_WSGI_DIR%>
+        WSGIProcessGroup watcher-api
+        WSGIApplicationGroup %{GLOBAL}
+        <IfVersion >= 2.4>
+            Require all granted
+        </IfVersion>
+        <IfVersion < 2.4>
+            Order allow,deny
+            Allow from all
+        </IfVersion>
+    </Directory>
+</VirtualHost>

devstack/lib/watcher

@@ -44,6 +44,9 @@ WATCHER_CONF_DIR=/etc/watcher
 WATCHER_CONF=$WATCHER_CONF_DIR/watcher.conf
 WATCHER_POLICY_JSON=$WATCHER_CONF_DIR/policy.json
 
+WATCHER_DEVSTACK_DIR=$WATCHER_DIR/devstack
+WATCHER_DEVSTACK_FILES_DIR=$WATCHER_DEVSTACK_DIR/files
+
 NOVA_CONF_DIR=/etc/nova
 NOVA_CONF=$NOVA_CONF_DIR/nova.conf
 
@@ -51,6 +54,13 @@ if is_ssl_enabled_service "watcher" || is_service_enabled tls-proxy; then
     WATCHER_SERVICE_PROTOCOL="https"
 fi
 
+WATCHER_USE_MOD_WSGI=$(trueorfalse True WATCHER_USE_MOD_WSGI)
+
+if is_suse; then
+    WATCHER_WSGI_DIR=${WATCHER_WSGI_DIR:-/srv/www/htdocs/watcher}
+else
+    WATCHER_WSGI_DIR=${WATCHER_WSGI_DIR:-/var/www/watcher}
+fi
 # Public facing bits
 WATCHER_SERVICE_HOST=${WATCHER_SERVICE_HOST:-$HOST_IP}
 WATCHER_SERVICE_PORT=${WATCHER_SERVICE_PORT:-9322}
@@ -74,10 +84,21 @@ function is_watcher_enabled {
     return 1
 }
 
+#_cleanup_watcher_apache_wsgi - Remove wsgi files,
+#disable and remove apache vhost file
+function _cleanup_watcher_apache_wsgi {
+    sudo rm -rf $WATCHER_WSGI_DIR
+    sudo rm -f $(apache_site_config_for watcher-api)
+    restart_apache_server
+}
+
 # cleanup_watcher() - Remove residual data files, anything left over from previous
 # runs that a clean run would need to clean up
 function cleanup_watcher {
     sudo rm -rf $WATCHER_STATE_PATH $WATCHER_AUTH_CACHE_DIR
+    if [[ "$WATCHER_USE_MOD_WSGI" == "True" ]]; then
+        _cleanup_watcher_apache_wsgi
+    fi
 }
 
 # configure_watcher() - Set config files, create data dirs, etc
@@ -108,6 +129,28 @@ function create_watcher_accounts {
         "$WATCHER_SERVICE_PROTOCOL://$WATCHER_SERVICE_HOST:$WATCHER_SERVICE_PORT"
 }
 
+# _config_watcher_apache_wsgi() - Set WSGI config files of watcher
+function _config_watcher_apache_wsgi {
+    local watcher_apache_conf
+    if [[ "$WATCHER_USE_MOD_WSGI" == "True" ]]; then
+        sudo mkdir -p $WATCHER_WSGI_DIR
+        sudo cp $WATCHER_DIR/watcher/api/app.wsgi $WATCHER_WSGI_DIR/app.wsgi
+        watcher_apache_conf=$(apache_site_config_for watcher-api)
+        sudo cp $WATCHER_DEVSTACK_FILES_DIR/apache-watcher-api.template $watcher_apache_conf
+        sudo sed -e "
+            s|%WATCHER_SERVICE_PORT%|$WATCHER_SERVICE_PORT|g;
+            s|%WATCHER_WSGI_DIR%|$WATCHER_WSGI_DIR|g;
+            s|%USER%|$STACK_USER|g;
+            s|%APIWORKERS%|$API_WORKERS|g;
+            s|%APACHE_NAME%|$APACHE_NAME|g;
+        " -i $watcher_apache_conf
+        enable_apache_site watcher-api
+        tail_log watcher-access /var/log/$APACHE_NAME/watcher-api-access.log
+        tail_log watcher-api /var/log/$APACHE_NAME/watcher-api.log
+   fi
+
+}
+
 # create_watcher_conf() - Create a new watcher.conf file
 function create_watcher_conf {
     # (Re)create ``watcher.conf``
@@ -126,7 +169,10 @@ function create_watcher_conf {
     iniset $WATCHER_CONF oslo_messaging_rabbit rabbit_password $RABBIT_PASSWORD
     iniset $WATCHER_CONF oslo_messaging_rabbit rabbit_host $RABBIT_HOST
 
+    iniset $WATCHER_CONF oslo_messaging_notifications driver "messagingv2"
+
     iniset $NOVA_CONF oslo_messaging_notifications topics "notifications,watcher_notifications"
+    iniset $NOVA_CONF notifications notify_on_state_change "vm_and_task_state"
 
     configure_auth_token_middleware $WATCHER_CONF watcher $WATCHER_AUTH_CACHE_DIR
     configure_auth_token_middleware $WATCHER_CONF watcher $WATCHER_AUTH_CACHE_DIR "watcher_clients_auth"
@@ -151,9 +197,13 @@ function create_watcher_conf {
         setup_colorized_logging $WATCHER_CONF DEFAULT
     else
         # Show user_name and project_name instead of user_id and project_id
-        iniset $WATCHER_CONF DEFAULT logging_context_format_string "%(asctime)s.%(msecs)03d %(levelname)s %(name)s [%(request_id)s %(user_name)s %(project_name)s] %(instance)s%(message)s"
+        iniset $WATCHER_CONF DEFAULT logging_context_format_string "%(asctime)s.%(msecs)03d %(levelname)s %(name)s [%(request_id)s %(project_domain)s %(user_name)s %(project_name)s] %(instance)s%(message)s"
     fi
 
+    #config apache files
+    if [[ "$WATCHER_USE_MOD_WSGI" == "True" ]]; then
+        _config_watcher_apache_wsgi
+    fi
     # Register SSL certificates if provided
     if is_ssl_enabled_service watcher; then
         ensure_certificates WATCHER
@@ -185,7 +235,7 @@ function init_watcher {
         recreate_database watcher
 
         # Create watcher schema
-        $WATCHER_BIN_DIR/watcher-db-manage --config-file $WATCHER_CONF create_schema
+        $WATCHER_BIN_DIR/watcher-db-manage --config-file $WATCHER_CONF upgrade
     fi
     create_watcher_cache_dir
 }
@@ -202,19 +252,26 @@ function install_watcherclient {
 function install_watcher {
     git_clone $WATCHER_REPO $WATCHER_DIR $WATCHER_BRANCH
     setup_develop $WATCHER_DIR
+    if [[ "$WATCHER_USE_MOD_WSGI" == "True" ]]; then
+        install_apache_wsgi
+    fi
 }
 
 # start_watcher_api() - Start the API process ahead of other things
 function start_watcher_api {
     # Get right service port for testing
+
     local service_port=$WATCHER_SERVICE_PORT
     local service_protocol=$WATCHER_SERVICE_PROTOCOL
     if is_service_enabled tls-proxy; then
         service_port=$WATCHER_SERVICE_PORT_INT
         service_protocol="http"
     fi
-
-    run_process watcher-api "$WATCHER_BIN_DIR/watcher-api --config-file $WATCHER_CONF"
+    if [[ "$WATCHER_USE_MOD_WSGI" == "True" ]]; then
+        restart_apache_server
+    else
+        run_process watcher-api "$WATCHER_BIN_DIR/watcher-api --config-file $WATCHER_CONF"
+    fi
     echo "Waiting for watcher-api to start..."
     if ! wait_for_service $SERVICE_TIMEOUT $service_protocol://$WATCHER_SERVICE_HOST:$service_port; then
         die $LINENO "watcher-api did not start"
@@ -237,7 +294,12 @@ function start_watcher {
 
 # stop_watcher() - Stop running processes (non-screen)
 function stop_watcher {
-    for serv in watcher-api watcher-decision-engine watcher-applier; do
+    if [[ "$WATCHER_USE_MOD_WSGI" == "True" ]]; then
+        disable_apache_site watcher-api
+    else
+        stop_process watcher-api
+    fi
+    for serv in watcher-decision-engine watcher-applier; do
         stop_process $serv
     done
 }

devstack/local.conf.compute

@@ -25,7 +25,7 @@ GLANCE_HOSTPORT=${SERVICE_HOST}:9292
 DATABASE_TYPE=mysql
 
 # Enable services (including neutron)
-ENABLED_SERVICES=n-cpu,n-api-meta,c-vol,q-agt
+ENABLED_SERVICES=n-cpu,n-api-meta,c-vol,q-agt,placement-client
 
 NOVA_VNC_ENABLED=True
 NOVNCPROXY_URL="http://$SERVICE_HOST:6080/vnc_auto.html"
@@ -44,3 +44,6 @@ LOGDAYS=2
 [[post-config|$NOVA_CONF]]
 [DEFAULT]
 compute_monitors=cpu.virt_driver
+notify_on_state_change = vm_and_task_state
+[notifications]
+notify_on_state_change = vm_and_task_state

devstack/local.conf.controller

@@ -17,16 +17,13 @@ NETWORK_GATEWAY=10.254.1.1 # Change this for your network
 
 MULTI_HOST=1
 
+
+#Set this to FALSE if do not want to run watcher-api behind mod-wsgi
+#WATCHER_USE_MOD_WSGI=TRUE
+
 # This is the controller node, so disable nova-compute
 disable_service n-cpu
 
-# Disable nova-network and use neutron instead
-disable_service n-net
-ENABLED_SERVICES+=,q-svc,q-dhcp,q-meta,q-agt,q-l3,neutron
-
-# Enable remote console access
-enable_service n-cauth
-
 # Enable the Watcher Dashboard plugin
 enable_plugin watcher-dashboard git://git.openstack.org/openstack/watcher-dashboard
 
@@ -39,9 +36,18 @@ enable_plugin ceilometer git://git.openstack.org/openstack/ceilometer
 # This is the controller node, so disable the ceilometer compute agent
 disable_service ceilometer-acompute
 
+# Enable the ceilometer api explicitly(bug:1667678)
+enable_service ceilometer-api
+
+# Enable the Gnocchi plugin
+enable_plugin gnocchi https://github.com/gnocchixyz/gnocchi
+
 LOGFILE=$DEST/logs/stack.sh.log
 LOGDAYS=2
 
 [[post-config|$NOVA_CONF]]
 [DEFAULT]
 compute_monitors=cpu.virt_driver
+notify_on_state_change = vm_and_task_state
+[notifications]
+notify_on_state_change = vm_and_task_state

devstack/plugin.sh

@@ -7,7 +7,7 @@ _XTRACE_WATCHER_PLUGIN=$(set +o | grep xtrace)
 set -o xtrace
 
 echo_summary "watcher's plugin.sh was called..."
-source $DEST/watcher/devstack/lib/watcher
+. $DEST/watcher/devstack/lib/watcher
 
 # Show all of defined environment variables
 (set -o posix; set)

doc/ext/term.py

@@ -1,4 +1,3 @@
-# -*- encoding: utf-8 -*-
 # Copyright (c) 2015 b<>com
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -23,7 +22,7 @@ from docutils import nodes
 from docutils.parsers import rst
 from docutils import statemachine
 
-from watcher.version import version_info
+from watcher.version import version_string
 
 
 class BaseWatcherDirective(rst.Directive):
@@ -75,7 +74,7 @@ class WatcherTerm(BaseWatcherDirective):
     # Inside your .rst file
     .. watcher-term:: import.path.to.your.DocumentedObject
 
-    This directive will then import the docstring and then interprete it.
+    This directive will then import the docstring and then interpret it.
     """
 
     # You need to put an import path as an argument for this directive to work
@@ -85,7 +84,12 @@ class WatcherTerm(BaseWatcherDirective):
         cls_path = self.arguments[0]
 
         try:
-            cls = importlib.import_module(cls_path)
+            try:
+                cls = importlib.import_module(cls_path)
+            except ImportError:
+                module_name, cls_name = cls_path.rsplit('.', 1)
+                mod = importlib.import_module(module_name)
+                cls = getattr(mod, cls_name)
         except Exception as exc:
             raise self.error(exc)
 
@@ -97,6 +101,72 @@ class WatcherTerm(BaseWatcherDirective):
         return node.children
 
 
+class WatcherFunc(BaseWatcherDirective):
+    """Directive to import a value returned by a func into the Watcher doc
+
+    **How to use it**
+
+    # inside your .py file
+    class Bar(object):
+
+        def foo(object):
+            return foo_string
+
+
+    # Inside your .rst file
+    .. watcher-func:: import.path.to.your.Bar.foo node_classname
+
+    node_classname is decumented here:
+    http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
+
+    This directive will then import the value and then interpret it.
+    """
+
+    # You need to put an import path as an argument for this directive to work
+    # required_arguments = 1
+    # optional_arguments = 1
+
+    option_spec = {'format': rst.directives.unchanged}
+    has_content = True
+
+    def run(self):
+        if not self.content:
+            error = self.state_machine.reporter.error(
+                'The "%s" directive is empty; content required.' % self.name,
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
+            return [error]
+
+        func_path = self.content[0]
+        try:
+            cls_path, func_name = func_path.rsplit('.', 1)
+            module_name, cls_name = cls_path.rsplit('.', 1)
+            mod = importlib.import_module(module_name)
+            cls = getattr(mod, cls_name)
+        except Exception as exc:
+            raise self.error(exc)
+
+        cls_obj = cls()
+        func = getattr(cls_obj, func_name)
+        textblock = func()
+        if not isinstance(textblock, str):
+            textblock = str(textblock)
+
+        self.add_textblock(textblock)
+
+        try:
+            node_class = getattr(nodes,
+                                 self.options.get('format', 'paragraph'))
+        except Exception as exc:
+            raise self.error(exc)
+
+        node = node_class()
+        node.document = self.state.document
+        self.state.nested_parse(self.result, 0, node)
+        return [node]
+
+
 def setup(app):
     app.add_directive('watcher-term', WatcherTerm)
-    return {'version': version_info.version_string()}
+    app.add_directive('watcher-func', WatcherFunc)
+    return {'version': version_string}

doc/ext/versioned_notifications.py

@@ -0,0 +1,133 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""
+This provides a sphinx extension able to list the implemented versioned
+notifications into the developer documentation.
+
+It is used via a single directive in the .rst file
+
+  .. versioned_notifications::
+
+"""
+
+from sphinx.util.compat import Directive
+from docutils import nodes
+
+from watcher.notifications import base as notification
+from watcher.objects import base
+
+
+class VersionedNotificationDirective(Directive):
+
+    SAMPLE_ROOT = 'doc/notification_samples/'
+    TOGGLE_SCRIPT = """
+<script>
+jQuery(document).ready(function(){
+    jQuery('#%s-div').toggle('show');
+    jQuery('#%s-hideshow').on('click', function(event) {
+        jQuery('#%s-div').toggle('show');
+    });
+});
+</script>
+"""
+
+    def run(self):
+        notifications = self._collect_notifications()
+        return self._build_markup(notifications)
+
+    def _collect_notifications(self):
+        base.WatcherObjectRegistry.register_notification_objects()
+        notifications = []
+        ovos = base.WatcherObjectRegistry.obj_classes()
+        for name, cls in ovos.items():
+            cls = cls[0]
+            if (issubclass(cls, notification.NotificationBase) and
+                    cls != notification.NotificationBase):
+
+                payload_name = cls.fields['payload'].objname
+                payload_cls = ovos[payload_name][0]
+                for sample in cls.samples:
+                    notifications.append((cls.__name__,
+                                          payload_cls.__name__,
+                                          sample))
+        return sorted(notifications)
+
+    def _build_markup(self, notifications):
+        content = []
+        cols = ['Event type', 'Notification class', 'Payload class', 'Sample']
+        table = nodes.table()
+        content.append(table)
+        group = nodes.tgroup(cols=len(cols))
+        table.append(group)
+
+        head = nodes.thead()
+        group.append(head)
+
+        for _ in cols:
+            group.append(nodes.colspec(colwidth=1))
+
+        body = nodes.tbody()
+        group.append(body)
+
+        # fill the table header
+        row = nodes.row()
+        body.append(row)
+        for col_name in cols:
+            col = nodes.entry()
+            row.append(col)
+            text = nodes.strong(text=col_name)
+            col.append(text)
+
+        # fill the table content, one notification per row
+        for name, payload, sample_file in notifications:
+            event_type = sample_file[0: -5].replace('-', '.')
+
+            row = nodes.row()
+            body.append(row)
+            col = nodes.entry()
+            row.append(col)
+            text = nodes.literal(text=event_type)
+            col.append(text)
+
+            col = nodes.entry()
+            row.append(col)
+            text = nodes.literal(text=name)
+            col.append(text)
+
+            col = nodes.entry()
+            row.append(col)
+            text = nodes.literal(text=payload)
+            col.append(text)
+
+            col = nodes.entry()
+            row.append(col)
+
+            with open(self.SAMPLE_ROOT + sample_file, 'r') as f:
+                sample_content = f.read()
+
+            event_type = sample_file[0: -5]
+            html_str = self.TOGGLE_SCRIPT % ((event_type, ) * 3)
+            html_str += ("<input type='button' id='%s-hideshow' "
+                         "value='hide/show sample'>" % event_type)
+            html_str += ("<div id='%s-div'><pre>%s</pre></div>"
+                         % (event_type, sample_content))
+
+            raw = nodes.raw('', html_str, format="html")
+            col.append(raw)
+
+        return content
+
+
+def setup(app):
+    app.add_directive('versioned_notifications',
+                      VersionedNotificationDirective)

doc/notification_samples/action-cancel-end.json

@@ -0,0 +1,41 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionCancelPayload",
+    "watcher_object.data": {
+      "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "input_parameters": {
+        "param2": 2,
+        "param1": 1
+      },
+      "fault": null,
+      "created_at": "2016-10-18T09:52:05Z",
+      "updated_at": null,
+      "state": "CANCELLED",
+      "action_plan": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseActionPlanPayload",
+        "watcher_object.data": {
+          "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+          "global_efficacy": [],
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "state": "CANCELLING",
+          "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "deleted_at": null
+        }
+      },
+      "parents": [],
+      "action_type": "nop",
+      "deleted_at": null
+    }
+  },
+  "event_type": "action.cancel.end",
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2017-01-01 00:00:00.000000",
+  "message_id": "530b409c-9b6b-459b-8f08-f93dbfeb4d41"
+}

doc/notification_samples/action-cancel-error.json

@@ -0,0 +1,51 @@
+{
+  "priority": "ERROR",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionCancelPayload",
+    "watcher_object.data": {
+      "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "input_parameters": {
+        "param2": 2,
+        "param1": 1
+      },
+      "fault": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "ExceptionPayload",
+        "watcher_object.data": {
+          "module_name": "watcher.tests.notifications.test_action_notification",
+          "exception": "WatcherException",
+          "exception_message": "TEST",
+          "function_name": "test_send_action_cancel_with_error"
+        }
+      },
+      "created_at": "2016-10-18T09:52:05Z",
+      "updated_at": null,
+      "state": "FAILED",
+      "action_plan": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseActionPlanPayload",
+        "watcher_object.data": {
+          "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+          "global_efficacy": [],
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "state": "CANCELLING",
+          "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "deleted_at": null
+        }
+      },
+      "parents": [],
+      "action_type": "nop",
+      "deleted_at": null
+    }
+  },
+  "event_type": "action.cancel.error",
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2017-01-01 00:00:00.000000",
+  "message_id": "530b409c-9b6b-459b-8f08-f93dbfeb4d41"
+}

doc/notification_samples/action-cancel-start.json

@@ -0,0 +1,41 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionCancelPayload",
+    "watcher_object.data": {
+      "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "input_parameters": {
+        "param2": 2,
+        "param1": 1
+      },
+      "fault": null,
+      "created_at": "2016-10-18T09:52:05Z",
+      "updated_at": null,
+      "state": "CANCELLING",
+      "action_plan": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseActionPlanPayload",
+        "watcher_object.data": {
+          "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+          "global_efficacy": [],
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "state": "CANCELLING",
+          "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "deleted_at": null
+        }
+      },
+      "parents": [],
+      "action_type": "nop",
+      "deleted_at": null
+    }
+  },
+  "event_type": "action.cancel.start",
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2017-01-01 00:00:00.000000",
+  "message_id": "530b409c-9b6b-459b-8f08-f93dbfeb4d41"
+}

doc/notification_samples/action-create.json

@@ -0,0 +1,40 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionCreatePayload",
+    "watcher_object.data": {
+      "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "input_parameters": {
+        "param2": 2,
+        "param1": 1
+      },
+      "created_at": "2016-10-18T09:52:05Z",
+      "updated_at": null,
+      "state": "PENDING",
+      "action_plan": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseActionPlanPayload",
+        "watcher_object.data": {
+          "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+          "global_efficacy": {},
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "state": "ONGOING",
+          "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "deleted_at": null
+        }
+      },
+      "parents": [],
+      "action_type": "nop",
+      "deleted_at": null
+    }
+  },
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2017-01-01 00:00:00.000000",
+  "event_type": "action.create",
+  "message_id": "530b409c-9b6b-459b-8f08-f93dbfeb4d41"
+}

doc/notification_samples/action-delete.json

@@ -0,0 +1,40 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionDeletePayload",
+    "watcher_object.data": {
+      "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "input_parameters": {
+        "param2": 2,
+        "param1": 1
+      },
+      "created_at": "2016-10-18T09:52:05Z",
+      "updated_at": null,
+      "state": "DELETED",
+      "action_plan": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseActionPlanPayload",
+        "watcher_object.data": {
+          "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+          "global_efficacy": {},
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "state": "ONGOING",
+          "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "deleted_at": null
+        }
+      },
+      "parents": [],
+      "action_type": "nop",
+      "deleted_at": null
+    }
+  },
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2017-01-01 00:00:00.000000",
+  "event_type": "action.delete",
+  "message_id": "530b409c-9b6b-459b-8f08-f93dbfeb4d41"
+}

doc/notification_samples/action-execution-end.json

@@ -0,0 +1,41 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionExecutionPayload",
+    "watcher_object.data": {
+      "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "input_parameters": {
+        "param2": 2,
+        "param1": 1
+      },
+      "fault": null,
+      "created_at": "2016-10-18T09:52:05Z",
+      "updated_at": null,
+      "state": "SUCCEEDED",
+      "action_plan": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseActionPlanPayload",
+        "watcher_object.data": {
+          "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+          "global_efficacy": [],
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "state": "ONGOING",
+          "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "deleted_at": null
+        }
+      },
+      "parents": [],
+      "action_type": "nop",
+      "deleted_at": null
+    }
+  },
+  "event_type": "action.execution.end",
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2017-01-01 00:00:00.000000",
+  "message_id": "530b409c-9b6b-459b-8f08-f93dbfeb4d41"
+}

doc/notification_samples/action-execution-error.json

@@ -0,0 +1,51 @@
+{
+  "priority": "ERROR",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionExecutionPayload",
+    "watcher_object.data": {
+      "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "input_parameters": {
+        "param2": 2,
+        "param1": 1
+      },
+      "fault": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "ExceptionPayload",
+        "watcher_object.data": {
+          "module_name": "watcher.tests.notifications.test_action_notification",
+          "exception": "WatcherException",
+          "exception_message": "TEST",
+          "function_name": "test_send_action_execution_with_error"
+        }
+      },
+      "created_at": "2016-10-18T09:52:05Z",
+      "updated_at": null,
+      "state": "FAILED",
+      "action_plan": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseActionPlanPayload",
+        "watcher_object.data": {
+          "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+          "global_efficacy":[],
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "state": "ONGOING",
+          "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "deleted_at": null
+        }
+      },
+      "parents": [],
+      "action_type": "nop",
+      "deleted_at": null
+    }
+  },
+  "event_type": "action.execution.error",
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2017-01-01 00:00:00.000000",
+  "message_id": "530b409c-9b6b-459b-8f08-f93dbfeb4d41"
+}

doc/notification_samples/action-execution-start.json

@@ -0,0 +1,41 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionExecutionPayload",
+    "watcher_object.data": {
+      "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "input_parameters": {
+        "param2": 2,
+        "param1": 1
+      },
+      "fault": null,
+      "created_at": "2016-10-18T09:52:05Z",
+      "updated_at": null,
+      "state": "ONGOING",
+      "action_plan": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseActionPlanPayload",
+        "watcher_object.data": {
+          "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+          "global_efficacy": [],
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "state": "ONGOING",
+          "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "deleted_at": null
+        }
+      },
+      "parents": [],
+      "action_type": "nop",
+      "deleted_at": null
+    }
+  },
+  "event_type": "action.execution.start",
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2017-01-01 00:00:00.000000",
+  "message_id": "530b409c-9b6b-459b-8f08-f93dbfeb4d41"
+}

doc/notification_samples/action-update.json

@@ -0,0 +1,49 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionUpdatePayload",
+    "watcher_object.data": {
+      "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "input_parameters": {
+        "param2": 2,
+        "param1": 1
+      },
+      "created_at": "2016-10-18T09:52:05Z",
+      "updated_at": null,
+      "state_update": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "ActionStateUpdatePayload",
+        "watcher_object.data": {
+          "old_state": "PENDING",
+          "state": "ONGOING"
+        }
+      },
+      "state": "ONGOING",
+      "action_plan": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseActionPlanPayload",
+        "watcher_object.data": {
+          "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+          "global_efficacy": {},
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "state": "ONGOING",
+          "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "deleted_at": null
+        }
+      },
+      "parents": [],
+      "action_type": "nop",
+      "deleted_at": null
+    }
+  },
+  "event_type": "action.update",
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2017-01-01 00:00:00.000000",
+  "message_id": "530b409c-9b6b-459b-8f08-f93dbfeb4d41"
+}

doc/notification_samples/action_plan-cancel-end.json

@@ -0,0 +1,55 @@
+{
+  "event_type": "action_plan.cancel.end",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.name": "ActionPlanCancelPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.data": {
+      "created_at": "2016-10-18T09:52:05Z",
+      "deleted_at": null,
+      "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "audit": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "TerseAuditPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "created_at": "2016-10-18T09:52:05Z",
+          "deleted_at": null,
+          "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "scope": [],
+          "audit_type": "ONESHOT",
+          "state": "SUCCEEDED",
+          "parameters": {},
+          "interval": null,
+          "updated_at": null
+        }
+      },
+      "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+      "fault": null,
+      "state": "CANCELLED",
+      "global_efficacy": [],
+      "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+      "strategy": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "created_at": "2016-10-18T09:52:05Z",
+          "deleted_at": null,
+          "name": "TEST",
+          "uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "parameters_spec": {},
+          "display_name": "test strategy",
+          "updated_at": null
+        }
+      },
+      "updated_at": null
+    }
+  },
+  "priority": "INFO",
+  "message_id": "3984dc2b-8aef-462b-a220-8ae04237a56e",
+  "timestamp": "2016-10-18 09:52:05.219414",
+  "publisher_id": "infra-optim:node0"
+}

doc/notification_samples/action_plan-cancel-error.json

@@ -0,0 +1,65 @@
+{
+  "event_type": "action_plan.cancel.error",
+  "publisher_id": "infra-optim:node0",
+  "priority": "ERROR",
+  "message_id": "9a45c5ae-0e21-4300-8fa0-5555d52a66d9",
+  "payload": {
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher",
+    "watcher_object.name": "ActionPlanCancelPayload",
+    "watcher_object.data": {
+      "fault": {
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "ExceptionPayload",
+        "watcher_object.data": {
+          "exception_message": "TEST",
+          "module_name": "watcher.tests.notifications.test_action_plan_notification",
+          "function_name": "test_send_action_plan_cancel_with_error",
+          "exception": "WatcherException"
+        }
+      },
+      "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+      "created_at": "2016-10-18T09:52:05Z",
+      "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+      "strategy": {
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.data": {
+          "uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "created_at": "2016-10-18T09:52:05Z",
+          "name": "TEST",
+          "updated_at": null,
+          "display_name": "test strategy",
+          "parameters_spec": {},
+          "deleted_at": null
+        }
+      },
+      "updated_at": null,
+      "deleted_at": null,
+      "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "audit": {
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "TerseAuditPayload",
+        "watcher_object.data": {
+          "parameters": {},
+          "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "created_at": "2016-10-18T09:52:05Z",
+          "scope": [],
+          "updated_at": null,
+          "audit_type": "ONESHOT",
+          "interval": null,
+          "deleted_at": null,
+          "state": "SUCCEEDED"
+        }
+      },
+      "global_efficacy": [],
+      "state": "CANCELLING"
+    }
+  },
+  "timestamp": "2016-10-18 09:52:05.219414"
+}

doc/notification_samples/action_plan-cancel-start.json

@@ -0,0 +1,55 @@
+{
+  "event_type": "action_plan.cancel.start",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.name": "ActionPlanCancelPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.data": {
+      "created_at": "2016-10-18T09:52:05Z",
+      "deleted_at": null,
+      "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "audit": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "TerseAuditPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "created_at": "2016-10-18T09:52:05Z",
+          "deleted_at": null,
+          "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "scope": [],
+          "audit_type": "ONESHOT",
+          "state": "SUCCEEDED",
+          "parameters": {},
+          "interval": null,
+          "updated_at": null
+        }
+      },
+      "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+      "fault": null,
+      "state": "CANCELLING",
+      "global_efficacy": [],
+      "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+      "strategy": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "created_at": "2016-10-18T09:52:05Z",
+          "deleted_at": null,
+          "name": "TEST",
+          "uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "parameters_spec": {},
+          "display_name": "test strategy",
+          "updated_at": null
+        }
+      },
+      "updated_at": null
+    }
+  },
+  "priority": "INFO",
+  "message_id": "3984dc2b-8aef-462b-a220-8ae04237a56e",
+  "timestamp": "2016-10-18 09:52:05.219414",
+  "publisher_id": "infra-optim:node0"
+}

doc/notification_samples/action_plan-create.json

@@ -0,0 +1,55 @@
+{
+  "publisher_id": "infra-optim:node0",
+  "payload": {
+    "watcher_object.version": "1.0",
+    "watcher_object.data": {
+      "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+      "strategy": {
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "display_name": "test strategy",
+          "name": "TEST",
+          "updated_at": null,
+          "parameters_spec": {},
+          "created_at": "2016-10-18T09:52:05Z",
+          "deleted_at": null
+        },
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "StrategyPayload"
+      },
+      "created_at": null,
+      "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "audit": {
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "name": "my_audit",
+          "audit_type": "ONESHOT",
+          "scope": [],
+          "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "parameters": {},
+          "interval": null,
+          "deleted_at": null,
+          "state": "PENDING",
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null
+        },
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "TerseAuditPayload"
+      },
+      "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+      "global_efficacy": {},
+      "deleted_at": null,
+      "state": "RECOMMENDED",
+      "updated_at": null
+    },
+    "watcher_object.namespace": "watcher",
+    "watcher_object.name": "ActionPlanCreatePayload"
+  },
+  "priority": "INFO",
+  "message_id": "5148bff1-ea06-4ad6-8e4e-8c85ca5eb629",
+  "event_type": "action_plan.create",
+  "timestamp": "2016-10-18 09:52:05.219414"
+}

doc/notification_samples/action_plan-delete.json

@@ -0,0 +1,55 @@
+{
+  "publisher_id": "infra-optim:node0",
+  "timestamp": "2016-10-18 09:52:05.219414",
+  "payload": {
+    "watcher_object.data": {
+      "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+      "created_at": "2016-10-18T09:52:05Z",
+      "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "audit": {
+        "watcher_object.data": {
+          "name": "my_audit",
+          "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "interval": null,
+          "audit_type": "ONESHOT",
+          "scope": [],
+          "updated_at": null,
+          "deleted_at": null,
+          "state": "PENDING",
+          "created_at": "2016-10-18T09:52:05Z",
+          "parameters": {}
+        },
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "TerseAuditPayload",
+        "watcher_object.namespace": "watcher"
+      },
+      "global_efficacy": {},
+      "updated_at": null,
+      "deleted_at": null,
+      "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+      "strategy": {
+        "watcher_object.data": {
+          "uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "created_at": "2016-10-18T09:52:05Z",
+          "name": "TEST",
+          "display_name": "test strategy",
+          "deleted_at": null,
+          "updated_at": null,
+          "parameters_spec": {}
+        },
+        "watcher_object.version": "1.0",
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.namespace": "watcher"
+      },
+      "state": "DELETED"
+    },
+    "watcher_object.version": "1.0",
+    "watcher_object.name": "ActionPlanDeletePayload",
+    "watcher_object.namespace": "watcher"
+  },
+  "event_type": "action_plan.delete",
+  "message_id": "3d137686-a1fd-4683-ab40-c4210aac2140",
+  "priority": "INFO"
+}

doc/notification_samples/action_plan-execution-end.json

@@ -0,0 +1,56 @@
+{
+  "event_type": "action_plan.execution.end",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.name": "ActionPlanActionPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.data": {
+      "created_at": "2016-10-18T09:52:05Z",
+      "deleted_at": null,
+      "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "audit": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "TerseAuditPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "created_at": "2016-10-18T09:52:05Z",
+          "deleted_at": null,
+          "name": "my_audit",
+          "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "scope": [],
+          "audit_type": "ONESHOT",
+          "state": "SUCCEEDED",
+          "parameters": {},
+          "interval": null,
+          "updated_at": null
+        }
+      },
+      "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+      "fault": null,
+      "state": "ONGOING",
+      "global_efficacy": [],
+      "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+      "strategy": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "created_at": "2016-10-18T09:52:05Z",
+          "deleted_at": null,
+          "name": "TEST",
+          "uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "parameters_spec": {},
+          "display_name": "test strategy",
+          "updated_at": null
+        }
+      },
+      "updated_at": null
+    }
+  },
+  "priority": "INFO",
+  "message_id": "3984dc2b-8aef-462b-a220-8ae04237a56e",
+  "timestamp": "2016-10-18 09:52:05.219414",
+  "publisher_id": "infra-optim:node0"
+}

doc/notification_samples/action_plan-execution-error.json

@@ -0,0 +1,66 @@
+{
+  "event_type": "action_plan.execution.error",
+  "publisher_id": "infra-optim:node0",
+  "priority": "ERROR",
+  "message_id": "9a45c5ae-0e21-4300-8fa0-5555d52a66d9",
+  "payload": {
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher",
+    "watcher_object.name": "ActionPlanActionPayload",
+    "watcher_object.data": {
+      "fault": {
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "ExceptionPayload",
+        "watcher_object.data": {
+          "exception_message": "TEST",
+          "module_name": "watcher.tests.notifications.test_action_plan_notification",
+          "function_name": "test_send_action_plan_action_with_error",
+          "exception": "WatcherException"
+        }
+      },
+      "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+      "created_at": "2016-10-18T09:52:05Z",
+      "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+      "strategy": {
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.data": {
+          "uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "created_at": "2016-10-18T09:52:05Z",
+          "name": "TEST",
+          "updated_at": null,
+          "display_name": "test strategy",
+          "parameters_spec": {},
+          "deleted_at": null
+        }
+      },
+      "updated_at": null,
+      "deleted_at": null,
+      "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "audit": {
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "TerseAuditPayload",
+        "watcher_object.data": {
+          "parameters": {},
+          "name": "my_audit",
+          "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "created_at": "2016-10-18T09:52:05Z",
+          "scope": [],
+          "updated_at": null,
+          "audit_type": "ONESHOT",
+          "interval": null,
+          "deleted_at": null,
+          "state": "PENDING"
+        }
+      },
+      "global_efficacy": [],
+      "state": "ONGOING"
+    }
+  },
+  "timestamp": "2016-10-18 09:52:05.219414"
+}

doc/notification_samples/action_plan-execution-start.json

@@ -0,0 +1,56 @@
+{
+  "event_type": "action_plan.execution.start",
+  "payload": {
+    "watcher_object.namespace": "watcher",
+    "watcher_object.name": "ActionPlanActionPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.data": {
+      "created_at": "2016-10-18T09:52:05Z",
+      "deleted_at": null,
+      "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "audit": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "TerseAuditPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "created_at": "2016-10-18T09:52:05Z",
+          "deleted_at": null,
+          "name": "my_audit",
+          "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "scope": [],
+          "audit_type": "ONESHOT",
+          "state": "PENDING",
+          "parameters": {},
+          "interval": null,
+          "updated_at": null
+        }
+      },
+      "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+      "fault": null,
+      "state": "ONGOING",
+      "global_efficacy": [],
+      "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+      "strategy": {
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "created_at": "2016-10-18T09:52:05Z",
+          "deleted_at": null,
+          "name": "TEST",
+          "uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "parameters_spec": {},
+          "display_name": "test strategy",
+          "updated_at": null
+        }
+      },
+      "updated_at": null
+    }
+  },
+  "priority": "INFO",
+  "message_id": "3984dc2b-8aef-462b-a220-8ae04237a56e",
+  "timestamp": "2016-10-18 09:52:05.219414",
+  "publisher_id": "infra-optim:node0"
+}

doc/notification_samples/action_plan-update.json

@@ -0,0 +1,64 @@
+{
+  "payload": {
+    "watcher_object.version": "1.0",
+    "watcher_object.data": {
+      "audit_uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+      "audit": {
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "name": "my_audit",
+          "audit_type": "ONESHOT",
+          "scope": [],
+          "created_at": "2016-10-18T09:52:05Z",
+          "uuid": "10a47dd1-4874-4298-91cf-eff046dbdb8d",
+          "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "interval": null,
+          "updated_at": null,
+          "state": "PENDING",
+          "deleted_at": null,
+          "parameters": {}
+        },
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "TerseAuditPayload"
+      },
+      "created_at": "2016-10-18T09:52:05Z",
+      "uuid": "76be87bd-3422-43f9-93a0-e85a577e3061",
+      "updated_at": null,
+      "state_update": {
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "old_state": "PENDING",
+          "state": "ONGOING"
+        },
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "ActionPlanStateUpdatePayload"
+      },
+      "state": "ONGOING",
+      "deleted_at": null,
+      "strategy_uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+      "strategy": {
+        "watcher_object.version": "1.0",
+        "watcher_object.data": {
+          "name": "TEST",
+          "uuid": "cb3d0b58-4415-4d90-b75b-1e96878730e3",
+          "display_name": "test strategy",
+          "created_at": "2016-10-18T09:52:05Z",
+          "updated_at": null,
+          "deleted_at": null,
+          "parameters_spec": {}
+        },
+        "watcher_object.namespace": "watcher",
+        "watcher_object.name": "StrategyPayload"
+      },
+      "global_efficacy": {}
+    },
+    "watcher_object.namespace": "watcher",
+    "watcher_object.name": "ActionPlanUpdatePayload"
+  },
+  "publisher_id": "infra-optim:node0",
+  "priority": "INFO",
+  "timestamp": "2016-10-18 09:52:05.219414",
+  "event_type": "action_plan.update",
+  "message_id": "0a8a7329-fd5a-4ec6-97d7-2b776ce51a4c"
+}

doc/notification_samples/audit-create.json

@@ -0,0 +1,72 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.data": {
+      "name": "my_audit",
+      "audit_type": "ONESHOT",
+      "parameters": {
+        "para2": "hello",
+        "para1": 3.2
+      },
+      "state": "PENDING",
+      "updated_at": null,
+      "deleted_at": null,
+      "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+      "goal": {
+        "watcher_object.data": {
+          "uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "name": "dummy",
+          "updated_at": null,
+          "deleted_at": null,
+          "efficacy_specification": [],
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy goal"
+        },
+        "watcher_object.name": "GoalPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "interval": null,
+      "scope": [],
+      "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+      "strategy": {
+        "watcher_object.data": {
+          "parameters_spec": {
+            "properties": {
+              "para2": {
+                "type": "string",
+                "default": "hello",
+                "description": "string parameter example"
+              },
+              "para1": {
+                "description": "number parameter example",
+                "maximum": 10.2,
+                "type": "number",
+                "default": 3.2,
+                "minimum": 1.0
+              }
+            }
+          },
+          "name": "dummy",
+          "uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "updated_at": null,
+          "deleted_at": null,
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy strategy"
+        },
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "created_at": "2016-11-04T16:29:20Z",
+      "uuid": "4a97b9dd-2023-43dc-b713-815bdd94d4d6"
+    },
+    "watcher_object.name": "AuditCreatePayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher"
+  },
+  "publisher_id": "infra-optim:localhost",
+  "timestamp": "2016-11-04 16:31:36.264673   ",
+  "event_type": "audit.create",
+  "message_id": "cbcf9f2c-7c53-4b4d-91ec-db49cca024b6"
+}

doc/notification_samples/audit-delete.json

@@ -0,0 +1,72 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.data": {
+      "name": "my_audit",
+      "audit_type": "ONESHOT",
+      "parameters": {
+        "para2": "hello",
+        "para1": 3.2
+      },
+      "state": "DELETED",
+      "updated_at": null,
+      "deleted_at": null,
+      "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+      "goal": {
+        "watcher_object.data": {
+          "uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "name": "dummy",
+          "updated_at": null,
+          "deleted_at": null,
+          "efficacy_specification": [],
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy goal"
+        },
+        "watcher_object.name": "GoalPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "interval": null,
+      "scope": [],
+      "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+      "strategy": {
+        "watcher_object.data": {
+          "parameters_spec": {
+            "properties": {
+              "para2": {
+                "type": "string",
+                "default": "hello",
+                "description": "string parameter example"
+              },
+              "para1": {
+                "description": "number parameter example",
+                "maximum": 10.2,
+                "type": "number",
+                "default": 3.2,
+                "minimum": 1.0
+              }
+            }
+          },
+          "name": "dummy",
+          "uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "updated_at": null,
+          "deleted_at": null,
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy strategy"
+        },
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "created_at": "2016-11-04T16:29:20Z",
+      "uuid": "4a97b9dd-2023-43dc-b713-815bdd94d4d6"
+    },
+    "watcher_object.name": "AuditDeletePayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher"
+  },
+  "publisher_id": "infra-optim:localhost",
+  "timestamp": "2016-11-04 16:31:36.264673   ",
+  "event_type": "audit.delete",
+  "message_id": "cbcf9f2c-7c53-4b4d-91ec-db49cca024b6"
+}

doc/notification_samples/audit-planner-end.json

@@ -0,0 +1,73 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.data": {
+      "name": "my_audit",
+      "audit_type": "ONESHOT",
+      "parameters": {
+        "para2": "hello",
+        "para1": 3.2
+      },
+      "state": "ONGOING",
+      "updated_at": null,
+      "deleted_at": null,
+      "fault": null,
+      "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+      "goal": {
+        "watcher_object.data": {
+          "uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "name": "dummy",
+          "updated_at": null,
+          "deleted_at": null,
+          "efficacy_specification": [],
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy goal"
+        },
+        "watcher_object.name": "GoalPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "interval": null,
+      "scope": [],
+      "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+      "strategy": {
+        "watcher_object.data": {
+          "parameters_spec": {
+            "properties": {
+              "para2": {
+                "type": "string",
+                "default": "hello",
+                "description": "string parameter example"
+              },
+              "para1": {
+                "description": "number parameter example",
+                "maximum": 10.2,
+                "type": "number",
+                "default": 3.2,
+                "minimum": 1.0
+              }
+            }
+          },
+          "name": "dummy",
+          "uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "updated_at": null,
+          "deleted_at": null,
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy strategy"
+        },
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "created_at": "2016-11-04T16:29:20Z",
+      "uuid": "4a97b9dd-2023-43dc-b713-815bdd94d4d6"
+    },
+    "watcher_object.name": "AuditActionPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher"
+  },
+  "publisher_id": "infra-optim:localhost",
+  "timestamp": "2016-11-04 16:31:36.264673   ",
+  "event_type": "audit.planner.end",
+  "message_id": "cbcf9f2c-7c53-4b4d-91ec-db49cca024b6"
+}

doc/notification_samples/audit-planner-error.json

@@ -0,0 +1,83 @@
+{
+  "priority": "ERROR",
+  "payload": {
+    "watcher_object.data": {
+      "name": "my_audit",
+      "audit_type": "ONESHOT",
+      "parameters": {
+        "para2": "hello",
+        "para1": 3.2
+      },
+      "state": "ONGOING",
+      "updated_at": null,
+      "deleted_at": null,
+      "fault": {
+        "watcher_object.data": {
+          "exception": "WatcherException",
+          "exception_message": "TEST",
+          "function_name": "test_send_audit_action_with_error",
+          "module_name": "watcher.tests.notifications.test_audit_notification"
+        },
+        "watcher_object.name": "ExceptionPayload",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0"
+      },
+      "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+      "goal": {
+        "watcher_object.data": {
+          "uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "name": "dummy",
+          "updated_at": null,
+          "deleted_at": null,
+          "efficacy_specification": [],
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy goal"
+        },
+        "watcher_object.name": "GoalPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "interval": null,
+      "scope": [],
+      "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+      "strategy": {
+        "watcher_object.data": {
+          "parameters_spec": {
+            "properties": {
+              "para2": {
+                "type": "string",
+                "default": "hello",
+                "description": "string parameter example"
+              },
+              "para1": {
+                "description": "number parameter example",
+                "maximum": 10.2,
+                "type": "number",
+                "default": 3.2,
+                "minimum": 1.0
+              }
+            }
+          },
+          "name": "dummy",
+          "uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "updated_at": null,
+          "deleted_at": null,
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy strategy"
+        },
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "created_at": "2016-11-04T16:29:20Z",
+      "uuid": "4a97b9dd-2023-43dc-b713-815bdd94d4d6"
+    },
+    "watcher_object.name": "AuditActionPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher"
+  },
+  "publisher_id": "infra-optim:localhost",
+  "timestamp": "2016-11-04 16:31:36.264673   ",
+  "event_type": "audit.planner.error",
+  "message_id": "cbcf9f2c-7c53-4b4d-91ec-db49cca024b6"
+}

doc/notification_samples/audit-planner-start.json

@@ -0,0 +1,73 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.data": {
+      "name": "my_audit",
+      "audit_type": "ONESHOT",
+      "parameters": {
+        "para2": "hello",
+        "para1": 3.2
+      },
+      "state": "ONGOING",
+      "updated_at": null,
+      "deleted_at": null,
+      "fault": null,
+      "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+      "goal": {
+        "watcher_object.data": {
+          "uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "name": "dummy",
+          "updated_at": null,
+          "deleted_at": null,
+          "efficacy_specification": [],
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy goal"
+        },
+        "watcher_object.name": "GoalPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "interval": null,
+      "scope": [],
+      "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+      "strategy": {
+        "watcher_object.data": {
+          "parameters_spec": {
+            "properties": {
+              "para2": {
+                "type": "string",
+                "default": "hello",
+                "description": "string parameter example"
+              },
+              "para1": {
+                "description": "number parameter example",
+                "maximum": 10.2,
+                "type": "number",
+                "default": 3.2,
+                "minimum": 1.0
+              }
+            }
+          },
+          "name": "dummy",
+          "uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "updated_at": null,
+          "deleted_at": null,
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy strategy"
+        },
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "created_at": "2016-11-04T16:29:20Z",
+      "uuid": "4a97b9dd-2023-43dc-b713-815bdd94d4d6"
+    },
+    "watcher_object.name": "AuditActionPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher"
+  },
+  "publisher_id": "infra-optim:localhost",
+  "timestamp": "2016-11-04 16:31:36.264673   ",
+  "event_type": "audit.planner.start",
+  "message_id": "cbcf9f2c-7c53-4b4d-91ec-db49cca024b6"
+}

doc/notification_samples/audit-strategy-end.json

@@ -0,0 +1,73 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.data": {
+      "name": "my_audit",
+      "audit_type": "ONESHOT",
+      "parameters": {
+        "para2": "hello",
+        "para1": 3.2
+      },
+      "state": "ONGOING",
+      "updated_at": null,
+      "deleted_at": null,
+      "fault": null,
+      "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+      "goal": {
+        "watcher_object.data": {
+          "uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "name": "dummy",
+          "updated_at": null,
+          "deleted_at": null,
+          "efficacy_specification": [],
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy goal"
+        },
+        "watcher_object.name": "GoalPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "interval": null,
+      "scope": [],
+      "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+      "strategy": {
+        "watcher_object.data": {
+          "parameters_spec": {
+            "properties": {
+              "para2": {
+                "type": "string",
+                "default": "hello",
+                "description": "string parameter example"
+              },
+              "para1": {
+                "description": "number parameter example",
+                "maximum": 10.2,
+                "type": "number",
+                "default": 3.2,
+                "minimum": 1.0
+              }
+            }
+          },
+          "name": "dummy",
+          "uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "updated_at": null,
+          "deleted_at": null,
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy strategy"
+        },
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "created_at": "2016-11-04T16:29:20Z",
+      "uuid": "4a97b9dd-2023-43dc-b713-815bdd94d4d6"
+    },
+    "watcher_object.name": "AuditActionPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher"
+  },
+  "publisher_id": "infra-optim:localhost",
+  "timestamp": "2016-11-04 16:31:36.264673   ",
+  "event_type": "audit.strategy.end",
+  "message_id": "cbcf9f2c-7c53-4b4d-91ec-db49cca024b6"
+}

doc/notification_samples/audit-strategy-error.json

@@ -0,0 +1,83 @@
+{
+  "priority": "ERROR",
+  "payload": {
+    "watcher_object.data": {
+      "name": "my_audit",
+      "audit_type": "ONESHOT",
+      "parameters": {
+        "para2": "hello",
+        "para1": 3.2
+      },
+      "state": "ONGOING",
+      "updated_at": null,
+      "deleted_at": null,
+      "fault": {
+        "watcher_object.data": {
+          "exception": "WatcherException",
+          "exception_message": "TEST",
+          "function_name": "test_send_audit_action_with_error",
+          "module_name": "watcher.tests.notifications.test_audit_notification"
+        },
+        "watcher_object.name": "ExceptionPayload",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0"
+      },
+      "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+      "goal": {
+        "watcher_object.data": {
+          "uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "name": "dummy",
+          "updated_at": null,
+          "deleted_at": null,
+          "efficacy_specification": [],
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy goal"
+        },
+        "watcher_object.name": "GoalPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "interval": null,
+      "scope": [],
+      "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+      "strategy": {
+        "watcher_object.data": {
+          "parameters_spec": {
+            "properties": {
+              "para2": {
+                "type": "string",
+                "default": "hello",
+                "description": "string parameter example"
+              },
+              "para1": {
+                "description": "number parameter example",
+                "maximum": 10.2,
+                "type": "number",
+                "default": 3.2,
+                "minimum": 1.0
+              }
+            }
+          },
+          "name": "dummy",
+          "uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "updated_at": null,
+          "deleted_at": null,
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy strategy"
+        },
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "created_at": "2016-11-04T16:29:20Z",
+      "uuid": "4a97b9dd-2023-43dc-b713-815bdd94d4d6"
+    },
+    "watcher_object.name": "AuditActionPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher"
+  },
+  "publisher_id": "infra-optim:localhost",
+  "timestamp": "2016-11-04 16:31:36.264673   ",
+  "event_type": "audit.strategy.error",
+  "message_id": "cbcf9f2c-7c53-4b4d-91ec-db49cca024b6"
+}

doc/notification_samples/audit-strategy-start.json

@@ -0,0 +1,73 @@
+{
+  "priority": "INFO",
+  "payload": {
+    "watcher_object.data": {
+      "name": "my_audit",
+      "audit_type": "ONESHOT",
+      "parameters": {
+        "para2": "hello",
+        "para1": 3.2
+      },
+      "state": "ONGOING",
+      "updated_at": null,
+      "deleted_at": null,
+      "fault": null,
+      "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+      "goal": {
+        "watcher_object.data": {
+          "uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "name": "dummy",
+          "updated_at": null,
+          "deleted_at": null,
+          "efficacy_specification": [],
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy goal"
+        },
+        "watcher_object.name": "GoalPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "interval": null,
+      "scope": [],
+      "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+      "strategy": {
+        "watcher_object.data": {
+          "parameters_spec": {
+            "properties": {
+              "para2": {
+                "type": "string",
+                "default": "hello",
+                "description": "string parameter example"
+              },
+              "para1": {
+                "description": "number parameter example",
+                "maximum": 10.2,
+                "type": "number",
+                "default": 3.2,
+                "minimum": 1.0
+              }
+            }
+          },
+          "name": "dummy",
+          "uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "updated_at": null,
+          "deleted_at": null,
+          "created_at": "2016-11-04T16:25:35Z",
+          "display_name": "Dummy strategy"
+        },
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.version": "1.0",
+        "watcher_object.namespace": "watcher"
+      },
+      "created_at": "2016-11-04T16:29:20Z",
+      "uuid": "4a97b9dd-2023-43dc-b713-815bdd94d4d6"
+    },
+    "watcher_object.name": "AuditActionPayload",
+    "watcher_object.version": "1.0",
+    "watcher_object.namespace": "watcher"
+  },
+  "publisher_id": "infra-optim:localhost",
+  "timestamp": "2016-11-04 16:31:36.264673   ",
+  "event_type": "audit.strategy.start",
+  "message_id": "cbcf9f2c-7c53-4b4d-91ec-db49cca024b6"
+}

doc/notification_samples/audit-update.json

@@ -0,0 +1,81 @@
+{
+  "publisher_id": "infra-optim:localhost",
+  "timestamp": "2016-11-04 16:51:38.722986   ",
+  "payload": {
+    "watcher_object.name": "AuditUpdatePayload",
+    "watcher_object.data": {
+      "name": "my_audit",
+      "strategy_uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+      "strategy": {
+        "watcher_object.name": "StrategyPayload",
+        "watcher_object.data": {
+          "name": "dummy",
+          "parameters_spec": {
+            "properties": {
+              "para2": {
+                "default": "hello",
+                "type": "string",
+                "description": "string parameter example"
+              },
+              "para1": {
+                "maximum": 10.2,
+                "default": 3.2,
+                "minimum": 1.0,
+                "description": "number parameter example",
+                "type": "number"
+              }
+            }
+          },
+          "updated_at": null,
+          "display_name": "Dummy strategy",
+          "deleted_at": null,
+          "uuid": "75234dfe-87e3-4f11-a0e0-3c3305d86a39",
+          "created_at": "2016-11-04T16:25:35Z"
+        },
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0"
+      },
+      "scope": [],
+      "created_at": "2016-11-04T16:51:21Z",
+      "uuid": "f1e0d912-afd9-4bf2-91ef-c99cd08cc1ef",
+      "goal_uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+      "goal": {
+        "watcher_object.name": "GoalPayload",
+        "watcher_object.data": {
+          "efficacy_specification": [],
+          "updated_at": null,
+          "name": "dummy",
+          "display_name": "Dummy goal",
+          "deleted_at": null,
+          "uuid": "bc830f84-8ae3-4fc6-8bc6-e3dd15e8b49a",
+          "created_at": "2016-11-04T16:25:35Z"
+        },
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0"
+      },
+      "parameters": {
+        "para2": "hello",
+        "para1": 3.2
+      },
+      "deleted_at": null,
+      "state_update": {
+        "watcher_object.name": "AuditStateUpdatePayload",
+        "watcher_object.data": {
+          "state": "ONGOING",
+          "old_state": "PENDING"
+        },
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0"
+      },
+      "interval": null,
+      "updated_at": null,
+      "state": "ONGOING",
+      "audit_type": "ONESHOT"
+    },
+    "watcher_object.namespace": "watcher",
+    "watcher_object.version": "1.0"
+  },
+  "priority": "INFO",
+  "event_type": "audit.update",
+  "message_id": "697fdf55-7252-4b6c-a2c2-5b9e85f6342c"
+}

doc/notification_samples/infra-optim-exception.json

@@ -0,0 +1,16 @@
+{
+    "event_type": "infra-optim.exception",
+    "payload": {
+        "watcher_object.data": {
+            "exception": "NoAvailableStrategyForGoal",
+            "exception_message": "No strategy could be found to achieve the server_consolidation goal.",
+            "function_name": "_aggregate_create_in_db",
+            "module_name": "watcher.objects.aggregate"
+        },
+        "watcher_object.name": "ExceptionPayload",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.version": "1.0"
+    },
+    "priority": "ERROR",
+    "publisher_id": "watcher-api:fake-mini"
+}

doc/notification_samples/service-update.json

@@ -0,0 +1,26 @@
+{
+    "payload": {
+        "watcher_object.name": "ServiceUpdatePayload",
+        "watcher_object.namespace": "watcher",
+        "watcher_object.data": {
+            "status_update": {
+                "watcher_object.name": "ServiceStatusUpdatePayload",
+                "watcher_object.namespace": "watcher",
+                "watcher_object.data": {
+                    "old_state": "ACTIVE",
+                    "state": "FAILED"
+                },
+                "watcher_object.version": "1.0"
+            },
+            "last_seen_up": "2016-09-22T08:32:06Z",
+            "name": "watcher-service",
+            "sevice_host": "controller"
+        },
+        "watcher_object.version": "1.0"
+    },
+    "event_type": "service.update",
+    "priority": "INFO",
+    "message_id": "3984dc2b-8aef-462b-a220-8ae04237a56e",
+    "timestamp": "2016-10-18 09:52:05.219414",
+    "publisher_id": "infra-optim:node0"
+}

doc/source/admin/apache-mod-wsgi.rst

@@ -0,0 +1,49 @@
+..
+      Except where otherwise noted, this document is licensed under Creative
+      Commons Attribution 3.0 License.  You can view the license at:
+
+          https://creativecommons.org/licenses/by/3.0/
+
+
+Installing API behind mod_wsgi
+==============================
+
+#. Install the Apache Service::
+
+    Fedora 21/RHEL7/CentOS7:
+      sudo yum install httpd
+
+    Fedora 22 (or higher):
+      sudo dnf install httpd
+
+    Debian/Ubuntu:
+      apt-get install apache2
+
+#. Copy ``etc/apache2/watcher.conf`` under the apache sites::
+
+    Fedora/RHEL7/CentOS7:
+      sudo cp etc/apache2/watcher /etc/httpd/conf.d/watcher.conf
+
+    Debian/Ubuntu:
+      sudo cp etc/apache2/watcher /etc/apache2/sites-available/watcher.conf
+
+#. Edit ``<apache-configuration-dir>/watcher.conf`` according to installation
+   and environment.
+
+   * Modify the ``WSGIDaemonProcess`` directive to set the ``user`` and
+     ``group`` values to appropriate user on your server.
+   * Modify the ``WSGIScriptAlias`` directive to point to the
+     watcher/api/app.wsgi script.
+   * Modify the ``Directory`` directive to set the path to the Watcher API
+     code.
+   * Modify the ``ErrorLog and CustomLog`` to redirect the logs to the right
+     directory.
+
+#. Enable the apache watcher site and reload::
+
+    Fedora/RHEL7/CentOS7:
+      sudo systemctl reload httpd
+
+   Debian/Ubuntu:
+    sudo a2ensite watcher
+    sudo service apache2 reload

doc/source/admin/index.rst

@@ -0,0 +1,12 @@
+===================
+Administrator Guide
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   apache-mod-wsgi
+   gmr
+   policy
+   ways-to-install
+   ../strategies/index

doc/source/admin/ways-to-install.rst

@@ -4,12 +4,13 @@
 
           https://creativecommons.org/licenses/by/3.0/
 
-==================
-Installing Watcher
-==================
+=======================
+Ways to install Watcher
+=======================
 
-This document describes how to install Watcher in order to use it. If you are
-intending to develop on or with Watcher, please read :doc:`../dev/environment`.
+This document describes some ways to install Watcher in order to use it.
+If you are intending to develop on or with Watcher,
+please read :doc:`../contributor/environment`.
 
 Prerequisites
 -------------
@@ -18,14 +19,14 @@ The source install instructions specifically avoid using platform specific
 packages, instead using the source for the code and the Python Package Index
 (PyPi_).
 
-.. _PyPi: http://pypi.python.org/pypi
+.. _PyPi: https://pypi.python.org/pypi
 
 It's expected that your system already has python2.7_, latest version of pip_,
 and git_ available.
 
-.. _python2.7: http://www.python.org
-.. _pip: http://www.pip-installer.org/en/latest/installing.html
-.. _git: http://git-scm.com/
+.. _python2.7: https://www.python.org
+.. _pip: https://pip.pypa.io/en/latest/installing/
+.. _git: https://git-scm.com/
 
 Your system shall also have some additional system libraries:
 
@@ -77,9 +78,10 @@ Install the Watcher modules dependencies:
 
     # pip install -r requirements.txt
 
-From here, refer to :doc:`configuration` to declare Watcher as a new service
-into Keystone and to configure its different modules. Once configured, you
-should be able to run the Watcher services by issuing these commands:
+From here, refer to :doc:`../configuration/configuring` to declare Watcher
+as a new service into Keystone and to configure its different modules.
+Once configured, you should be able to run the Watcher services by issuing
+these commands:
 
 .. code-block:: bash
 
@@ -107,7 +109,7 @@ installed on your system.
 
 Once installed, you still need to declare Watcher as a new service into
 Keystone and to configure its different modules, which you can find described
-in :doc:`configuration`.
+in :doc:`../configuration/configuring`.
 
 
 Installing from packages: Debian (experimental)
@@ -124,9 +126,9 @@ Here is single Dockerfile snippet you can use to run your Docker container:
     MAINTAINER David TARDIVEL <david.tardivel@b-com.com>
 
     RUN  apt-get update
-    RUN  apt-get dist-upgrade -y
-    RUN  apt-get install -y vim  net-tools
-    RUN  apt-get install -yt experimental watcher-api
+    RUN  apt-get dist-upgrade
+    RUN  apt-get install vim  net-tools
+    RUN  apt-get install experimental watcher-api
 
     CMD ["/usr/bin/watcher-api"]
 

doc/source/api/index.rst

@@ -0,0 +1,4 @@
+.. toctree::
+   :maxdepth: 1
+
+   v1

doc/source/api/v1.rst

@@ -20,6 +20,17 @@ Goals
 .. autotype:: watcher.api.controllers.v1.goal.Goal
    :members:
 
+Strategies
+==========
+
+.. rest-controller:: watcher.api.controllers.v1.strategy:StrategiesController
+   :webprefix: /v1/strategies
+
+.. autotype:: watcher.api.controllers.v1.strategy.StrategyCollection
+   :members:
+
+.. autotype:: watcher.api.controllers.v1.strategy.Strategy
+   :members:
 
 Audit Templates
 ===============
@@ -75,3 +86,15 @@ Actions
 
 .. autotype:: watcher.api.controllers.v1.action.Action
    :members:
+
+Scoring Engine
+==============
+
+.. rest-controller:: watcher.api.controllers.v1.scoring_engine:ScoringEngineController
+   :webprefix: /v1/scoring_engine
+
+.. autotype:: watcher.api.controllers.v1.scoring_engine.ScoringEngineCollection
+   :members:
+
+.. autotype:: watcher.api.controllers.v1.scoring_engine.ScoringEngine
+   :members:

doc/source/architecture.rst

@@ -21,7 +21,7 @@ Overview
 Below you will find a diagram, showing the main components of Watcher:
 
 .. image:: ./images/architecture.svg
-   :width: 100%
+   :width: 110%
 
 
 .. _components_definition:
@@ -37,13 +37,12 @@ AMQP Bus
 The AMQP message bus handles internal asynchronous communications between the
 different Watcher components.
 
-.. _cluster_history_db_definition:
+.. _cluster_datasource_definition:
 
-Cluster History Database
-------------------------
+Datasource
+----------
 
-This component stores the data related to the
-:ref:`Cluster History <cluster_history_definition>`.
+This component stores the metrics related to the cluster.
 
 It can potentially rely on any appropriate storage system (InfluxDB, OpenTSDB,
 MongoDB,...) but will probably be more performant when using
@@ -51,14 +50,6 @@ MongoDB,...) but will probably be more performant when using
 which are optimized for handling time series data, which are arrays of numbers
 indexed by time (a datetime or a datetime range).
 
-.. _cluster_model_db_definition:
-
-Cluster Model Database
-------------------------
-
-This component stores the data related to the
-:ref:`Cluster Data Model <cluster_data_model_definition>`.
-
 .. _archi_watcher_api_definition:
 
 Watcher API
@@ -128,7 +119,7 @@ The watcher command-line interface (CLI) can be used to interact with the
 Watcher system in order to control it or to know its current status.
 
 Please, read `the detailed documentation about Watcher CLI
-<https://factory.b-com.com/www/watcher/doc/python-watcherclient/>`_.
+<https://docs.openstack.org/python-watcherclient/latest/cli/>`_.
 
 .. _archi_watcher_dashboard_definition:
 
@@ -139,7 +130,7 @@ The Watcher Dashboard can be used to interact with the Watcher system through
 Horizon in order to control it or to know its current status.
 
 Please, read `the detailed documentation about Watcher Dashboard
-<http://docs.openstack.org/developer/watcher-dashboard/>`_.
+<https://docs.openstack.org/watcher-dashboard/latest>`_.
 
 .. _archi_watcher_database_definition:
 
@@ -179,7 +170,7 @@ Unless specified, it then selects the most appropriate :ref:`strategy
 goal.
 
 The :ref:`Strategy <strategy_definition>` is then dynamically loaded (via
-`stevedore <http://docs.openstack.org/developer/stevedore/>`_). The
+`stevedore <https://docs.openstack.org/stevedore/latest>`_). The
 :ref:`Watcher Decision Engine <watcher_decision_engine_definition>` executes
 the strategy.
 
@@ -193,8 +184,8 @@ data:
   :ref:`Managed resources <managed_resource_definition>` (e.g., the data stored
   in the Nova database). These models gives a strategy the ability to reason on
   the current state of a given :ref:`cluster <cluster_definition>`.
-- The data stored in the :ref:`Cluster History Database
-  <cluster_history_db_definition>` which provides information about the past of
+- The data stored in the :ref:`Cluster Datasource
+  <cluster_datasource_definition>` which provides information about the past of
   the :ref:`Cluster <cluster_definition>`.
 
 Here below is a sequence diagram showing how the Decision Engine builds and
@@ -298,7 +289,7 @@ The :ref:`Watcher Decision Engine <watcher_decision_engine_definition>` also
 builds the :ref:`Cluster Data Model <cluster_data_model_definition>`. This
 data model is needed by the :ref:`Strategy <strategy_definition>` to know the
 current state and topology of the audited
-:ref:`Openstack cluster <cluster_definition>`.
+:ref:`OpenStack cluster <cluster_definition>`.
 
 The :ref:`Watcher Decision Engine <watcher_decision_engine_definition>` calls
 the **execute()** method of the instantiated
@@ -316,7 +307,7 @@ This method finds an appropriate scheduling of
 :ref:`Actions <action_definition>` taking into account some scheduling rules
 (such as priorities between actions).
 It generates a new :ref:`Action Plan <action_plan_definition>` with status
-**RECOMMENDED** and saves it into the:ref:`Watcher Database
+**RECOMMENDED** and saves it into the :ref:`Watcher Database
 <watcher_database_definition>`. The saved action plan is now a scheduled flow
 of actions to which a global efficacy is associated alongside a number of
 :ref:`Efficacy Indicators <efficacy_indicator_definition>` as specified by the
@@ -416,6 +407,9 @@ be one of the following:
 -  **CANCELLED** : the :ref:`Audit <audit_definition>` was in **PENDING** or
    **ONGOING** state and was cancelled by the
    :ref:`Administrator <administrator_definition>`
+-  **SUSPENDED** : the :ref:`Audit <audit_definition>` was in **ONGOING**
+   state and was suspended by the
+   :ref:`Administrator <administrator_definition>`
 
 The following diagram shows the different possible states of an
 :ref:`Audit <audit_definition>` and what event makes the state change to a new
@@ -450,8 +444,12 @@ state may be one of the following:
    stored in the :ref:`Watcher database <watcher_database_definition>` but is
    not returned any more through the Watcher APIs.
 -  **CANCELLED** : the :ref:`Action Plan <action_plan_definition>` was in
-   **PENDING** or **ONGOING** state and was cancelled by the
+   **RECOMMENDED**, **PENDING** or **ONGOING** state and was cancelled by the
    :ref:`Administrator <administrator_definition>`
+-  **SUPERSEDED** : the :ref:`Action Plan <action_plan_definition>` was in
+   RECOMMENDED state and was automatically superseded by Watcher, due to an
+   expiration delay or an update of the
+   :ref:`Cluster data model <cluster_data_model_definition>`
 
 
 The following diagram shows the different possible states of an

doc/source/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -11,26 +10,44 @@
 # implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
+import os
+import sys
+
 from watcher import version as watcher_version
+from watcher import objects
+
+objects.register_all()
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('./'))
 
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    'oslo_config.sphinxconfiggen',
-    'oslosphinx',
+    'oslo_config.sphinxext',
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinxcontrib.httpdomain',
     'sphinxcontrib.pecanwsme.rest',
     'stevedore.sphinxext',
     'wsmeext.sphinxext',
-    'watcher.doc',
+    'ext.term',
+    'ext.versioned_notifications',
+    'oslo_config.sphinxconfiggen',
+    'openstackdocstheme',
 ]
 
 wsme_protocols = ['restjson']
-config_generator_config_file = '../../etc/watcher/watcher-config-generator.conf'
+config_generator_config_file = [(
+    '../../etc/watcher/oslo-config-generator/watcher.conf',
+    '_static/watcher')]
 sample_config_basename = 'watcher'
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -55,7 +72,7 @@ copyright = u'OpenStack Foundation'
 # The full version, including alpha/beta/rc tags.
 release = watcher_version.version_info.release_string()
 # The short X.Y version.
-version = watcher_version.version_info.version_string()
+version = watcher_version.version_string
 
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['watcher.']
@@ -67,6 +84,8 @@ exclude_patterns = [
     # them when scanning for input files.
     'man/footer.rst',
     'man/general-options.rst',
+    'strategies/strategy-template.rst',
+    'image_src/plantuml/README.rst',
 ]
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -76,6 +95,8 @@ add_function_parentheses = True
 # unit titles (such as .. function::).
 add_module_names = True
 
+suppress_warnings = ['app.add_directive']
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
@@ -101,12 +122,20 @@ man_pages = [
 # Sphinx are currently 'default' and 'sphinxdoc'.
 # html_theme_path = ["."]
 # html_theme = '_theme'
+html_theme = 'openstackdocs'
 # html_static_path = ['static']
-html_theme_options = {'incubating': True}
+# html_theme_options = {}
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
+#openstackdocstheme options
+repository_name = 'openstack/watcher'
+bug_project = 'watcher'
+bug_tag = ''
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).

doc/source/config-generator.conf

@@ -1 +0,0 @@
-../../etc/watcher/watcher-config-generator.conf

doc/source/configuration/configuring.rst

@@ -15,7 +15,7 @@ Service overview
 ================
 
 The Watcher system is a collection of services that provides support to
-optimize your IAAS plateform. The Watcher service may, depending upon
+optimize your IaaS platform. The Watcher service may, depending upon
 configuration, interact with several other OpenStack services. This includes:
 
 - the OpenStack Identity service (`keystone`_) for request authentication and
@@ -27,7 +27,7 @@ configuration, interact with several other OpenStack services. This includes:
 
 The Watcher service includes the following components:
 
-- ``watcher-decision-engine``: runs audit on part of your IAAS and return an
+- ``watcher-decision-engine``: runs audit on part of your IaaS and return an
   action plan in order to optimize resource placement.
 - ``watcher-api``: A RESTful API that processes application requests by sending
   them to the watcher-decision-engine over RPC.
@@ -37,7 +37,7 @@ The Watcher service includes the following components:
 - `watcher-dashboard`_: An Horizon plugin for interacting with the Watcher
   service.
 
-Additionally, the Bare Metal service has certain external dependencies, which
+Additionally, the Watcher service has certain external dependencies, which
 are very similar to other OpenStack services:
 
 - A database to store audit and action plan information and state. You can set
@@ -86,7 +86,6 @@ Configure the Identity service for the Watcher service
         --tenant=KEYSTONE_SERVICE_PROJECT_NAME
       $ keystone user-role-add --user=watcher \
         --tenant=KEYSTONE_SERVICE_PROJECT_NAME --role=admin
-      $ keystone user-role-add --user=watcher --tenant=admin --role=admin
 
    or (by using python-openstackclient 1.8.0+)
 
@@ -97,7 +96,6 @@ Configure the Identity service for the Watcher service
         --project=KEYSTONE_SERVICE_PROJECT_NAME
       $ openstack role add --project KEYSTONE_SERVICE_PROJECT_NAME \
         --user watcher admin
-      $ openstack role add --user watcher --project admin admin
 
 
 #. You must register the Watcher Service with the Identity Service so that
@@ -169,7 +167,7 @@ these following commands::
 
     $ git clone git://git.openstack.org/openstack/watcher
     $ cd watcher/
-    $ tox -econfig
+    $ tox -e genconfig
     $ vi etc/watcher/watcher.conf.sample
 
 
@@ -351,7 +349,7 @@ so that the watcher service is configured for your needs.
     [nova_client]
 
     # Version of Nova API to use in novaclient. (string value)
-    #api_version = 2
+    #api_version = 2.53
     api_version = 2.1
 
 #. Create the Watcher Service database tables::
@@ -368,15 +366,14 @@ Configure Nova compute
 Please check your hypervisor configuration to correctly handle
 `instance migration`_.
 
-.. _`instance migration`: http://docs.openstack.org/admin-guide-cloud/compute-configuring-migrations.html
+.. _`instance migration`: https://docs.openstack.org/nova/latest/admin/migration.html
 
 Configure Measurements
 ======================
 
 You can configure and install Ceilometer by following the documentation below :
 
-#. http://docs.openstack.org/developer/ceilometer
-#. http://docs.openstack.org/kilo/install-guide/install/apt/content/ceilometer-nova.html
+#. https://docs.openstack.org/ceilometer/latest
 
 The built-in strategy 'basic_consolidation' provided by watcher requires
 "**compute.node.cpu.percent**" and "**cpu_util**" measurements to be collected
@@ -388,13 +385,13 @@ the OpenStack site.
 You can use 'ceilometer meter-list' to list the available meters.
 
 For more information:
-http://docs.openstack.org/developer/ceilometer/measurements.html
+https://docs.openstack.org/ceilometer/latest/admin/telemetry-measurements.html
 
 Ceilometer is designed to collect measurements from OpenStack services and from
 other external components. If you would like to add new meters to the currently
 existing ones, you need to follow the documentation below:
 
-#. http://docs.openstack.org/developer/ceilometer/new_meters.html
+#. https://docs.openstack.org/ceilometer/latest/contributor/new_meters.html#meters
 
 The Ceilometer collector uses a pluggable storage system, meaning that you can
 pick any database system you prefer.
@@ -426,12 +423,32 @@ to Watcher receives Nova notifications in ``watcher_notifications`` as well.
     into which Nova services will publish events ::
 
       [oslo_messaging_notifications]
-      driver = messaging
+      driver = messagingv2
       topics = notifications,watcher_notifications
 
   * Restart the Nova services.
 
 
+Configure Cinder Notifications
+==============================
+
+Watcher can also consume notifications generated by the Cinder services, in
+order to build or update, in real time, its cluster data model related to
+storage resources. To do so, you have to update the Cinder configuration
+file on controller and volume nodes, in order to let Watcher receive Cinder
+notifications in a dedicated ``watcher_notifications`` channel.
+
+  * In the file ``/etc/cinder/cinder.conf``, update the section
+    ``[oslo_messaging_notifications]``, by redefining the list of topics
+    into which Cinder services will publish events ::
+
+      [oslo_messaging_notifications]
+      driver = messagingv2
+      topics = notifications,watcher_notifications
+
+  * Restart the Cinder services.
+
+
 Workers
 =======
 

doc/source/configuration/index.rst

@@ -0,0 +1,5 @@
+.. toctree::
+   :maxdepth: 1
+
+   configuring
+   watcher

doc/source/configuration/watcher.rst

@@ -0,0 +1,11 @@
+.. _watcher_sample_configuration_files:
+
+------------
+watcher.conf
+------------
+
+The ``watcher.conf`` file contains most of the options to configure the
+Watcher services.
+
+.. show-options::
+   :config-file: etc/watcher/oslo-config-generator/watcher.conf

doc/source/contributor/contributing.rst

@@ -24,8 +24,8 @@ signed OpenStack's contributor's agreement.
 
 .. seealso::
 
-   * http://docs.openstack.org/infra/manual/developers.html
-   * http://wiki.openstack.org/CLA
+   * https://docs.openstack.org/infra/manual/developers.html
+   * https://wiki.openstack.org/CLA
 
 LaunchPad Project
 -----------------
@@ -37,22 +37,22 @@ notifications of important events.
 
 .. seealso::
 
-   * http://launchpad.net
-   * http://launchpad.net/watcher
-   * http://launchpad.net/~openstack
+   * https://launchpad.net
+   * https://launchpad.net/watcher
+   * https://launchpad.net/~openstack
 
 
 Project Hosting Details
 -----------------------
 
 Bug tracker
-    http://launchpad.net/watcher
+    https://launchpad.net/watcher
 
 Mailing list (prefix subjects with ``[watcher]`` for faster responses)
-    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
+    https://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
 
 Wiki
-    http://wiki.openstack.org/Watcher
+    https://wiki.openstack.org/Watcher
 
 Code Hosting
     https://git.openstack.org/cgit/openstack/watcher
@@ -64,8 +64,9 @@ IRC Channel
     ``#openstack-watcher`` (changelog_)
 
 Weekly Meetings
-    on Wednesdays at 14:00 UTC on even weeks, 9:00 UTC on odd weeks, in the
-    ``#openstack-meeting-4`` IRC channel (`meetings logs`_)
+    On Wednesdays at 14:00 UTC on even weeks in the ``#openstack-meeting-4``
+    IRC channel, 13:00 UTC on odd weeks in the ``#openstack-meeting-alt``
+    IRC channel (`meetings logs`_)
 
 .. _changelog: http://eavesdrop.openstack.org/irclogs/%23openstack-watcher/
 .. _meetings logs:  http://eavesdrop.openstack.org/meetings/watcher/

doc/source/contributor/devstack.rst

@@ -24,8 +24,8 @@ Watcher plugin::
 For more detailed instructions, see `Detailed DevStack Instructions`_. Check
 out the `DevStack documentation`_ for more information regarding DevStack.
 
-.. _PluginModelDocs: http://docs.openstack.org/developer/devstack/plugins.html
-.. _DevStack documentation: http://docs.openstack.org/developer/devstack/
+.. _PluginModelDocs: https://docs.openstack.org/devstack/latest/plugins.html
+.. _DevStack documentation: https://docs.openstack.org/devstack/latest
 
 Detailed DevStack Instructions
 ==============================
@@ -37,7 +37,7 @@ Detailed DevStack Instructions
    needed (i.e., no computes are needed if you want to just experiment with
    the Watcher services). These servers can be VMs running on your local
    machine via VirtualBox if you prefer. DevStack currently recommends that
-   you use Ubuntu 14.04 LTS. The servers should also have connections to the
+   you use Ubuntu 16.04 LTS. The servers should also have connections to the
    same network such that they are all able to communicate with one another.
 
 #. For each server, clone the DevStack repository and create the stack user::
@@ -92,6 +92,12 @@ Detailed DevStack Instructions
    Note: if you want to use a specific branch, specify WATCHER_BRANCH in the
    local.conf file. By default it will use the master branch.
 
+   Note: watcher-api will default run under apache/httpd, set the variable
+   WATCHER_USE_MOD_WSGI=FALSE if you do not wish to run under apache/httpd.
+   For development environment it is suggested to set WATHCER_USE_MOD_WSGI
+   to FALSE. For Production environment it is suggested to keep it at the
+   default TRUE value.
+
 #. Start stacking from the controller node::
 
        ./devstack/stack.sh
@@ -193,6 +199,37 @@ must exist in every other compute node's stack user's authorized_keys file and
 every compute node's public ECDSA key needs to be in every other compute
 node's root user's known_hosts file.
 
+Disable serial console
+----------------------
+
+Serial console needs to be disabled for live migration to work.
+
+On both the controller and compute node, in /etc/nova/nova.conf
+
+[serial_console]
+enabled = False
+
+Alternatively, in devstack's local.conf:
+
+[[post-config|$NOVA_CONF]]
+[serial_console]
+#enabled=false
+
+
+VNC server configuration
+------------------------
+
+The VNC server listening parameter needs to be set to any address so
+that the server can accept connections from all of the compute nodes.
+
+On both the controller and compute node, in /etc/nova/nova.conf
+
+vncserver_listen = 0.0.0.0
+
+Alternatively, in devstack's local.conf:
+
+VNCSERVER_LISTEN=0.0.0.0
+
 
 Environment final checkup
 -------------------------

doc/source/contributor/environment.rst

@@ -4,7 +4,7 @@
 
           https://creativecommons.org/licenses/by/3.0/
 
-.. _watcher_developement_environment:
+.. _watcher_development_environment:
 
 =========================================
 Set up a development environment manually
@@ -16,8 +16,8 @@ for development purposes.
 To install Watcher from packaging, refer instead to Watcher `User
 Documentation`_.
 
-.. _`Git Repository`: http://git.openstack.org/cgit/openstack/watcher
-.. _`User Documentation`: http://docs.openstack.org/developer/watcher/
+.. _`Git Repository`: https://git.openstack.org/cgit/openstack/watcher
+.. _`User Documentation`: https://docs.openstack.org/watcher/latest/
 
 Prerequisites
 =============
@@ -25,7 +25,7 @@ Prerequisites
 This document assumes you are using Ubuntu or Fedora, and that you have the
 following tools available on your system:
 
-- Python_ 2.7 and 3.4
+- Python_ 2.7 and 3.5
 - git_
 - setuptools_
 - pip_
@@ -35,10 +35,10 @@ following tools available on your system:
 **Reminder**: If you're successfully using a different platform, or a
 different version of the above, please document your configuration here!
 
-.. _Python: http://www.python.org/
-.. _git: http://git-scm.com/
-.. _setuptools: http://pypi.python.org/pypi/setuptools
-.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.org/en/latest/install.html
+.. _Python: https://www.python.org/
+.. _git: https://git-scm.com/
+.. _setuptools: https://pypi.python.org/pypi/setuptools
+.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/install.html
 
 Getting the latest code
 =======================
@@ -69,22 +69,25 @@ itself.
 
 These dependencies can be installed from PyPi_ using the Python tool pip_.
 
-.. _PyPi: http://pypi.python.org/
-.. _pip: http://pypi.python.org/pypi/pip
+.. _PyPi: https://pypi.python.org/
+.. _pip: https://pypi.python.org/pypi/pip
 
 However, your system *may* need additional dependencies that `pip` (and by
 extension, PyPi) cannot satisfy. These dependencies should be installed
 prior to using `pip`, and the installation method may vary depending on
 your platform.
 
-* Ubuntu 14.04::
+* Ubuntu 16.04::
 
     $ sudo apt-get install python-dev libssl-dev libmysqlclient-dev libffi-dev
 
-* Fedora 19+::
+* Fedora 24+::
 
-    $ sudo yum install openssl-devel libffi-devel mysql-devel
+    $ sudo dnf install redhat-rpm-config gcc python-devel libxml2-devel
 
+* CentOS 7::
+
+    $ sudo yum install gcc python-devel libxml2-devel libxslt-devel mariadb-devel
 
 PyPi Packages and VirtualEnv
 ----------------------------
@@ -122,7 +125,7 @@ You can re-activate this virtualenv for your current shell using:
 
 For more information on virtual environments, see virtualenv_.
 
-.. _virtualenv: http://www.virtualenv.org/
+.. _virtualenv: https://www.virtualenv.org/
 
 
 
@@ -172,11 +175,12 @@ The HTML files are available into ``doc/build`` directory.
 Configure the Watcher services
 ==============================
 
-Watcher services require a configuration file. There is a sample configuration
-file that can be used to get started:
+Watcher services require a configuration file. Use tox to generate
+a sample configuration file that can be used to get started:
 
 .. code-block:: bash
 
+  $ tox -e genconfig
   $ cp etc/watcher.conf.sample etc/watcher.conf
 
 Most of the default configuration should be enough to get you going, but you
@@ -190,7 +194,7 @@ still need to configure the following sections:
   message bus
 
 So if you need some more details on how to configure one or more of these
-sections, please do have a look at :doc:`../deploy/configuration` before
+sections, please do have a look at :doc:`../configuration/configuring` before
 continuing.
 
 
@@ -236,7 +240,7 @@ To run the Watcher Applier service, use:
     (watcher) $ watcher-applier
 
 Default configuration of these services are available into ``/etc/watcher``
-directory. See :doc:`../deploy/configuration` for details on how Watcher is
+directory. See :doc:`../configuration/configuring` for details on how Watcher is
 configured. By default, Watcher is configured with SQL backends.
 
 

doc/source/contributor/index.rst

@@ -0,0 +1,8 @@
+.. toctree::
+   :maxdepth: 1
+
+   environment
+   devstack
+   notifications
+   testing
+   rally_link

doc/source/contributor/notifications.rst

@@ -0,0 +1,13 @@
+..
+      Except where otherwise noted, this document is licensed under Creative
+      Commons Attribution 3.0 License.  You can view the license at:
+
+          https://creativecommons.org/licenses/by/3.0/
+
+.. _watcher_notifications:
+
+========================
+Notifications in Watcher
+========================
+
+.. versioned_notifications::

doc/source/contributor/plugin/action-plugin.rst

@@ -30,12 +30,12 @@ implement:
    implement. This is the first function to be called by the
    :ref:`applier <watcher_applier_definition>` before any further processing
    and its role is to validate the input parameters that were provided to it.
- - The :py:meth:`~.BaseAction.precondition` is called before the execution of
+ - The :py:meth:`~.BaseAction.pre_condition` is called before the execution of
    an action. This method is a hook that can be used to perform some
    initializations or to make some more advanced validation on its input
    parameters. If you wish to block the execution based on this factor, you
    simply have to ``raise`` an exception.
- - The :py:meth:`~.BaseAction.postcondition` is called after the execution of
+ - The :py:meth:`~.BaseAction.post_condition` is called after the execution of
    an action. As this function is called regardless of whether an action
    succeeded or not, this can prove itself useful to perform cleanup
    operations.
@@ -71,11 +71,11 @@ Here is an example showing how you can write a plugin called ``DummyAction``:
             # Does nothing
             pass
 
-        def precondition(self):
+        def pre_condition(self):
             # No pre-checks are done here
             pass
 
-        def postcondition(self):
+        def post_condition(self):
             # Nothing done here
             pass
 
@@ -178,7 +178,7 @@ Here below is how you would proceed to register ``DummyAction`` using pbr_:
     watcher_actions =
         dummy = thirdparty.dummy:DummyAction
 
-.. _pbr: http://docs.openstack.org/developer/pbr/
+.. _pbr: https://docs.openstack.org/pbr/latest
 
 
 Using action plugins
@@ -217,3 +217,11 @@ which is only able to process the Watcher built-in actions. Therefore, you will
 either have to use an existing third-party planner or :ref:`implement another
 planner <implement_planner_plugin>` that will be able to take into account your
 new action plugin.
+
+
+Test your new action
+====================
+
+In order to test your new action via a manual test or a Tempest test, you can
+use the  :py:class:`~.Actuator` strategy and pass it one or more actions to
+execute. This way, you can isolate your action to see if it works as expected.

doc/source/contributor/plugin/base-setup.rst

@@ -22,7 +22,7 @@ Pre-requisites
 We assume that you have set up a working Watcher development environment. So if
 this not already the case, you can check out our documentation which explains
 how to set up a :ref:`development environment
-<watcher_developement_environment>`.
+<watcher_development_environment>`.
 
 .. _development environment:
 
@@ -34,7 +34,7 @@ First off, we need to create the project structure. To do so, we can use
 generate the skeleton of our project::
 
     $ virtualenv thirdparty
-    $ source thirdparty/bin/activate
+    $ . thirdparty/bin/activate
     $ pip install cookiecutter
     $ cookiecutter https://github.com/openstack-dev/cookiecutter
 

doc/source/contributor/plugin/cdmc-plugin.rst

@@ -22,12 +22,14 @@ cluster data model collectors within Watcher.
 Creating a new plugin
 =====================
 
-In order to create a new model, you have to:
+In order to create a new cluster data model collector, you have to:
 
 - Extend the :py:class:`~.base.BaseClusterDataModelCollector` class.
 - Implement its :py:meth:`~.BaseClusterDataModelCollector.execute` abstract
   method to return your entire cluster data model that this method should
   build.
+- Implement its :py:meth:`~.BaseClusterDataModelCollector.audit_scope_handler`
+  abstract property to return your audit scope handler.
 - Implement its :py:meth:`~.Goal.notification_endpoints` abstract property to
   return the list of all the :py:class:`~.base.NotificationEndpoint` instances
   that will be responsible for handling incoming notifications in order to
@@ -57,6 +59,10 @@ Here is an example showing how you can write a plugin called
             # Do something here...
             return model
 
+        @property
+        def audit_scope_handler(self):
+            return None
+
         @property
         def notification_endpoints(self):
             return []
@@ -65,6 +71,49 @@ This implementation is the most basic one. So in order to get a better
 understanding on how to implement a more advanced cluster data model collector,
 have a look at the :py:class:`~.NovaClusterDataModelCollector` class.
 
+Define a custom model
+=====================
+
+As you may have noticed in the above example, we are reusing an existing model
+provided by Watcher. However, this model can be easily customized by
+implementing a new class that would implement the :py:class:`~.Model` abstract
+base class. Here below is simple example on how to proceed in implementing a
+custom Model:
+
+.. code-block:: python
+
+    # Filepath = <PROJECT_DIR>/thirdparty/dummy.py
+    # Import path = thirdparty.dummy
+
+    from watcher.decision_engine.model import base as modelbase
+    from watcher.decision_engine.model.collector import base
+
+
+    class MyModel(modelbase.Model):
+
+        def to_string(self):
+            return 'MyModel'
+
+
+    class DummyClusterDataModelCollector(base.BaseClusterDataModelCollector):
+
+        def execute(self):
+            model = MyModel()
+            # Do something here...
+            return model
+
+        @property
+        def notification_endpoints(self):
+            return []
+
+Here below is the abstract ``Model`` class that every single cluster data model
+should implement:
+
+.. autoclass:: watcher.decision_engine.model.base.Model
+    :members:
+    :special-members: __init__
+    :noindex:
+
 Define configuration parameters
 ===============================
 
@@ -92,6 +141,10 @@ class method as followed:
             # Do something here...
             return model
 
+        @property
+        def audit_scope_handler(self):
+            return None
+
         @property
         def notification_endpoints(self):
             return []
@@ -155,7 +208,7 @@ Here below is how to register ``DummyClusterDataModelCollector`` using pbr_:
     watcher_cluster_data_model_collectors =
         dummy = thirdparty.dummy:DummyClusterDataModelCollector
 
-.. _pbr: http://docs.openstack.org/developer/pbr/
+.. _pbr: http://docs.openstack.org/pbr/latest
 
 
 Add new notification endpoints
@@ -225,5 +278,5 @@ At this point, you can use your new cluster data model plugin in your
     # [...]
     dummy_collector = self.collector_manager.get_cluster_model_collector(
         "dummy")  # "dummy" is the name of the entry point we declared earlier
-    dummy_model = collector.get_latest_cluster_data_model()
+    dummy_model = dummy_collector.get_latest_cluster_data_model()
     # Do some stuff with this model

doc/source/contributor/plugin/goal-plugin.rst

@@ -60,8 +60,8 @@ Here is an example showing how you can define a new ``NewGoal`` goal plugin:
     # import path: thirdparty.new
 
     from watcher._i18n import _
+    from watcher.decision_engine.goal import base
     from watcher.decision_engine.goal.efficacy import specs
-    from watcher.decision_engine.strategy.strategies import base
 
     class NewGoal(base.Goal):
 
@@ -79,11 +79,11 @@ Here is an example showing how you can define a new ``NewGoal`` goal plugin:
 
         @classmethod
         def get_efficacy_specification(cls):
-            return specs.UnclassifiedStrategySpecification()
+            return specs.Unclassified()
 
 
 As you may have noticed, the :py:meth:`~.Goal.get_efficacy_specification`
-method returns an :py:meth:`~.UnclassifiedStrategySpecification` instance which
+method returns an :py:meth:`~.Unclassified` instance which
 is provided by Watcher. This efficacy specification is useful during the
 development process of your goal as it corresponds to an empty specification.
 If you want to learn more about what efficacy specifications are used for or to
@@ -123,10 +123,11 @@ Here below is how you would proceed to register ``NewGoal`` using pbr_:
         new_goal = thirdparty.new:NewGoal
 
 
-To get a better understanding on how to implement a more advanced goal,
-have a look at the :py:class:`~.ServerConsolidation` class.
+To get a better understanding on how to implement a more advanced goal, have
+a look at the
+:py:class:`watcher.decision_engine.goal.goals.ServerConsolidation` class.
 
-.. _pbr: http://docs.openstack.org/developer/pbr/
+.. _pbr: https://docs.openstack.org/pbr/latest
 
 .. _implement_efficacy_specification:
 

doc/source/contributor/plugin/index.rst

@@ -0,0 +1,11 @@
+.. toctree::
+   :maxdepth: 1
+
+   base-setup
+   action-plugin
+   cdmc-plugin
+   goal-plugin
+   planner-plugin
+   scoring-engine-plugin
+   strategy-plugin
+   plugins

doc/source/contributor/plugin/planner-plugin.rst

@@ -39,7 +39,7 @@ Here is an example showing how you can write a planner plugin called
 
     # Filepath = third-party/third_party/dummy.py
     # Import path = third_party.dummy
-    import uuid
+    from oslo_utils import uuidutils
     from watcher.decision_engine.planner import base
 
 
@@ -47,7 +47,7 @@ Here is an example showing how you can write a planner plugin called
 
         def _create_action_plan(self, context, audit_id):
             action_plan_dict = {
-                'uuid': uuid.uuid4(),
+                'uuid': uuidutils.generate_uuid(),
                 'audit_id': audit_id,
                 'first_action_id': None,
                 'state': objects.action_plan.State.RECOMMENDED
@@ -145,7 +145,7 @@ Here below is how you would proceed to register ``DummyPlanner`` using pbr_:
     watcher_planners =
         dummy = third_party.dummy:DummyPlanner
 
-.. _pbr: http://docs.openstack.org/developer/pbr/
+.. _pbr: https://docs.openstack.org/pbr/latest
 
 
 Using planner plugins

doc/source/contributor/plugin/scoring-engine-plugin.rst

@@ -37,7 +37,8 @@ Create a new scoring engine plugin
 
 In order to create a new scoring engine you have to:
 
-- Extend the :py:class:`~.ScoringEngine` class
+- Extend the :py:class:`watcher.decision_engine.scoring.base.ScoringEngine`
+  class
 - Implement its :py:meth:`~.ScoringEngine.get_name` method to return the
   **unique** ID of the new scoring engine you want to create. This unique ID
   should be the same as the name of :ref:`the entry point we will declare later
@@ -124,7 +125,8 @@ scoring engine deployed as a web service on external servers:
 Abstract Plugin Class
 =====================
 
-Here below is the abstract :py:class:`~.ScoringEngine` class:
+Here below is the abstract
+:py:class:`watcher.decision_engine.scoring.base.ScoringEngine` class:
 
 .. autoclass:: watcher.decision_engine.scoring.base.ScoringEngine
     :members:
@@ -188,7 +190,7 @@ the :py:class:`~.DummyScoringContainer` and the way it is configured in
     watcher_scoring_engine_containers =
         new_scoring_container = thirdparty.new:NewContainer
 
-.. _pbr: http://docs.openstack.org/developer/pbr/
+.. _pbr: https://docs.openstack.org/pbr/latest/
 
 
 Using scoring engine plugins

doc/source/contributor/plugin/strategy-plugin.rst

@@ -43,7 +43,7 @@ In order to create a new strategy, you have to:
   Note: Do not use a variable to return the translated string so it can be
   automatically collected by the translation tool.
 - Implement its :py:meth:`~.BaseStrategy.get_translatable_display_name`
-  class method to return the translation key (actually the english display
+  class method to return the translation key (actually the English display
   name) of your new strategy. The value return should be the same as the
   string translated in :py:meth:`~.BaseStrategy.get_display_name`.
 - Implement its :py:meth:`~.BaseStrategy.execute` method to return the
@@ -219,7 +219,7 @@ Here below is how you would proceed to register ``NewStrategy`` using pbr_:
 To get a better understanding on how to implement a more advanced strategy,
 have a look at the :py:class:`~.BasicConsolidation` class.
 
-.. _pbr: http://docs.openstack.org/developer/pbr/
+.. _pbr: https://docs.openstack.org/pbr/latest
 
 Using strategy plugins
 ======================
@@ -245,75 +245,70 @@ Querying metrics
 
 A large set of metrics, generated by OpenStack modules, can be used in your
 strategy implementation. To collect these metrics, Watcher provides a
-`Helper`_ to the Ceilometer API, which makes this API reusable and easier
-to used.
+`Helper`_ for two data sources which are `Ceilometer`_ and `Monasca`_. If you
+wish to query metrics from a different data source, you can implement your own
+and directly use it from within your new strategy. Indeed, strategies in
+Watcher have the cluster data models decoupled from the data sources which
+means that you may keep the former while changing the latter.
+The recommended way for you to support a new data source is to implement a new
+helper that would encapsulate within separate methods the queries you need to
+perform. To then use it, you would just have to instantiate it within your
+strategy.
 
-If you want to use your own metrics database backend, please refer to the
-`Ceilometer developer guide`_. Indeed, Ceilometer's pluggable model allows
-for various types of backends.  A list of the available backends is located
-here_. The Ceilosca project is a good example of how to create your own
-pluggable backend.
+If you want to use Ceilometer but with your own metrics database backend,
+please refer to the `Ceilometer developer guide`_. The list of the available
+Ceilometer backends is located here_. The `Ceilosca`_ project is a good example
+of how to create your own pluggable backend. Moreover, if your strategy
+requires new metrics not covered by Ceilometer, you can add them through a
+`Ceilometer plugin`_.
 
-Finally, if your strategy requires new metrics not covered by Ceilometer, you
-can add them through a Ceilometer `plugin`_.
 
 .. _`Helper`: https://github.com/openstack/watcher/blob/master/watcher/decision_engine/cluster/history/ceilometer.py
-.. _`Ceilometer developer guide`: http://docs.openstack.org/developer/ceilometer/architecture.html#storing-the-data
-.. _`here`: http://docs.openstack.org/developer/ceilometer/install/dbreco.html#choosing-a-database-backend
-.. _`plugin`: http://docs.openstack.org/developer/ceilometer/plugins.html
+.. _`Ceilometer developer guide`: https://docs.openstack.org/ceilometer/latest/contributor/architecture.html#storing-accessing-the-data
+.. _`Ceilometer`: https://docs.openstack.org/ceilometer/latest
+.. _`Monasca`: https://github.com/openstack/monasca-api/blob/master/docs/monasca-api-spec.md
+.. _`here`: https://docs.openstack.org/ceilometer/latest/contributor/install/dbreco.html#choosing-a-database-backend
+.. _`Ceilometer plugin`: https://docs.openstack.org/ceilometer/latest/contributor/plugins.html
 .. _`Ceilosca`: https://github.com/openstack/monasca-ceilometer/blob/master/ceilosca/ceilometer/storage/impl_monasca.py
 
+Read usage metrics using the Watcher Datasource Helper
+------------------------------------------------------
 
-Read usage metrics using the Python binding
--------------------------------------------
-
-You can find the information about the Ceilometer Python binding on the
-OpenStack `ceilometer client python API documentation
-<http://docs.openstack.org/developer/python-ceilometerclient/api.html>`_
-
-To facilitate the process, Watcher provides the ``osc`` attribute to every
-strategy which includes clients to major OpenStack services, including
-Ceilometer. So to access it within your strategy, you can do the following:
+The following code snippet shows how to invoke a Datasource Helper class:
 
 .. code-block:: py
 
-    # Within your strategy "execute()"
-    cclient = self.osc.ceilometer
-    # TODO: Do something here
+    from watcher.datasource import ceilometer as ceil
+    from watcher.datasource import monasca as mon
+
+    @property
+    def ceilometer(self):
+        if self._ceilometer is None:
+            self._ceilometer = ceil.CeilometerHelper(osc=self.osc)
+        return self._ceilometer
+
+    @property
+    def monasca(self):
+        if self._monasca is None:
+            self._monasca = mon.MonascaHelper(osc=self.osc)
+        return self._monasca
 
 Using that you can now query the values for that specific metric:
 
 .. code-block:: py
 
-    query = None  # e.g. [{'field': 'foo', 'op': 'le', 'value': 34},]
-    value_cpu = cclient.samples.list(
-        meter_name='cpu_util',
-        limit=10, q=query)
-
-
-Read usage metrics using the Watcher Cluster History Helper
------------------------------------------------------------
-
-Here below is the abstract ``BaseClusterHistory`` class of the Helper.
-
-.. autoclass:: watcher.decision_engine.cluster.history.base.BaseClusterHistory
-    :members:
-    :noindex:
-
-The following code snippet shows how to create a Cluster History class:
-
-.. code-block:: py
-
-    from watcher.decision_engine.cluster.history import ceilometer as ceil
-
-    query_history  = ceil.CeilometerClusterHistory()
-
-Using that you can now query the values for that specific metric:
-
-.. code-block:: py
-
-    query_history.statistic_aggregation(resource_id=compute_node.uuid,
-                                  meter_name='compute.node.cpu.percent',
-                                  period="7200",
-                                  aggregate='avg'
-                                  )
+        if self.config.datasource == "ceilometer":
+            resource_id = "%s_%s" % (node.uuid, node.hostname)
+            return self.ceilometer.statistic_aggregation(
+                resource_id=resource_id,
+                meter_name='compute.node.cpu.percent',
+                period="7200",
+                aggregate='avg',
+            )
+        elif self.config.datasource == "monasca":
+            statistics = self.monasca.statistic_aggregation(
+                meter_name='compute.node.cpu.percent',
+                dimensions=dict(hostname=node.uuid),
+                period=7200,
+                aggregate='avg'
+            )

doc/source/contributor/testing.rst

@@ -14,7 +14,7 @@ Unit tests
 ==========
 
 All unit tests should be run using `tox`_. To run the same unit tests that are
-executing onto `Gerrit`_ which includes ``py34``, ``py27`` and ``pep8``, you
+executing onto `Gerrit`_ which includes ``py35``, ``py27`` and ``pep8``, you
 can issue the following command::
 
     $ workon watcher
@@ -26,7 +26,7 @@ If you want to only run one of the aforementioned, you can then issue one of
 the following::
 
     $ workon watcher
-    (watcher) $ tox -e py34
+    (watcher) $ tox -e py35
     (watcher) $ tox -e py27
     (watcher) $ tox -e pep8
 
@@ -41,10 +41,18 @@ you can run the desired test::
     $ workon watcher
     (watcher) $ tox -e py27 -- -r watcher.tests.api
 
-.. _os-testr: http://docs.openstack.org/developer/os-testr/
+.. _os-testr: https://docs.openstack.org/os-testr/latest
 
 When you're done, deactivate the virtualenv::
 
     $ deactivate
 
-.. include:: ../../../watcher_tempest_plugin/README.rst
+.. _tempest_tests:
+
+Tempest tests
+=============
+
+Tempest tests for Watcher has been migrated to the external repo
+`watcher-tempest-plugin`_.
+
+.. _watcher-tempest-plugin: https://github.com/openstack/watcher-tempest-plugin

doc/source/deploy/conf-files.rst

@@ -1,14 +0,0 @@
-.. _watcher_sample_configuration_files:
-
-==================================
-Watcher sample configuration files
-==================================
-
-watcher.conf
-~~~~~~~~~~~~
-
-The ``watcher.conf`` file contains most of the options to configure the
-Watcher services.
-
-.. literalinclude:: ../watcher.conf.sample
-   :language: ini

doc/source/glossary.rst

@@ -65,6 +65,14 @@ Audit
 
 .. _audit_template_definition:
 
+Audit Scope
+===========
+
+An Audit Scope is a set of audited resources. Audit Scope should be defined
+in each Audit Template (which contains the Audit settings).
+
+.. _audit_scope_definition:
+
 Audit Template
 ==============
 
@@ -75,7 +83,7 @@ Audit Template
 Availability Zone
 =================
 
-Please, read `the official OpenStack definition of an Availability Zone <http://docs.openstack.org/developer/nova/aggregates.html#availability-zones-azs>`_.
+Please, read `the official OpenStack definition of an Availability Zone <https://docs.openstack.org/nova/latest/user/aggregates.html#availability-zones-azs>`_.
 
 .. _cluster_definition:
 
@@ -96,32 +104,19 @@ The :ref:`Cluster <cluster_definition>` may be divided in one or several
 
 .. _cluster_data_model_definition:
 
-Cluster Data Model
-==================
+Cluster Data Model (CDM)
+========================
 
 .. watcher-term:: watcher.decision_engine.model.collector.base
 
-.. _cluster_history_definition:
-
-Cluster History
-===============
-
-.. watcher-term:: watcher.decision_engine.cluster.history.base
 
 .. _controller_node_definition:
 
 Controller Node
 ===============
 
-A controller node is a machine that typically runs the following core OpenStack
-services:
-
--  Keystone: for identity and service management
--  Cinder scheduler: for volumes management
--  Glance controller: for image management
--  Neutron controller: for network management
--  Nova controller: for global compute resources management with services
-   such as nova-scheduler, nova-conductor and nova-network.
+Please, read `the official OpenStack definition of a Controller Node
+<https://docs.openstack.org/nova/latest/install/overview.html#controller>`_.
 
 In many configurations, Watcher will reside on a controller node even if it
 can potentially be hosted on a dedicated machine.
@@ -132,7 +127,7 @@ Compute node
 ============
 
 Please, read `the official OpenStack definition of a Compute Node
-<http://docs.openstack.org/openstack-ops/content/compute_nodes.html>`_.
+<https://docs.openstack.org/nova/latest/install/overview.html#compute>`_.
 
 .. _customer_definition:
 
@@ -164,7 +159,8 @@ Goal
 Host Aggregate
 ==============
 
-Please, read `the official OpenStack definition of a Host Aggregate <http://docs.openstack.org/developer/nova/aggregates.html>`_.
+Please, read `the official OpenStack definition of a Host Aggregate
+<https://docs.openstack.org/nova/latest/user/aggregates.html>`_.
 
 .. _instance_definition:
 
@@ -203,18 +199,18 @@ the Watcher system can act on.
 Here are some examples of
 :ref:`Managed resource types <managed_resource_definition>`:
 
--  `Nova Host Aggregates <http://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::HostAggregate>`_
--  `Nova Servers <http://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::Server>`_
--  `Cinder Volumes <http://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Cinder::Volume>`_
--  `Neutron Routers <http://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Router>`_
--  `Neutron Networks <http://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Net>`_
--  `Neutron load-balancers <http://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::LoadBalancer>`_
--  `Sahara Hadoop Cluster <http://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Sahara::Cluster>`_
+-  `Nova Host Aggregates <https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Nova::HostAggregate>`_
+-  `Nova Servers <https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Nova::Server>`_
+-  `Cinder Volumes <https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Cinder::Volume>`_
+-  `Neutron Routers <https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Neutron::Router>`_
+-  `Neutron Networks <https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Neutron::Net>`_
+-  `Neutron load-balancers <https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Neutron::LoadBalancer>`_
+-  `Sahara Hadoop Cluster <https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Sahara::Cluster>`_
 -  ...
 
-It can be any of the `the official list of available resource types defined in
+It can be any of `the official list of available resource types defined in
 OpenStack for HEAT
-<http://docs.openstack.org/developer/heat/template_guide/openstack.html>`_.
+<https://docs.openstack.org/heat/latest/template_guide/openstack.html>`_.
 
 .. _efficacy_indicator_definition:
 

doc/source/image_src/plantuml/action_plan_state_machine.txt

@@ -7,10 +7,14 @@ ONGOING --> FAILED: Something failed while executing\nthe Action Plan in the Wat
 ONGOING --> SUCCEEDED: The Watcher Applier executed\nthe Action Plan successfully
 FAILED --> DELETED : Administrator removes\nAction Plan
 SUCCEEDED --> DELETED : Administrator removes\nAction Plan
-ONGOING --> CANCELLED : Administrator cancels\nAction Plan
+ONGOING --> CANCELLING : Administrator cancels\nAction Plan
+CANCELLING --> CANCELLED : The Watcher Applier cancelled\nthe Action Plan successfully
+CANCELLING --> FAILED : Something failed while cancelling\nthe Action Plan in the Watcher Applier
 RECOMMENDED --> CANCELLED : Administrator cancels\nAction Plan
+RECOMMENDED --> SUPERSEDED : The Watcher Decision Engine supersedes\nAction Plan
 PENDING --> CANCELLED : Administrator cancels\nAction Plan
 CANCELLED --> DELETED
+SUPERSEDED --> DELETED
 DELETED --> [*]
 
 @enduml

doc/source/image_src/plantuml/audit_state_machine.txt

@@ -4,11 +4,14 @@
 PENDING --> ONGOING: Audit request is received\nby the Watcher Decision Engine
 ONGOING --> FAILED: Audit fails\n(no solution found, technical error, ...)
 ONGOING --> SUCCEEDED: The Watcher Decision Engine\ncould find at least one Solution
+ONGOING --> SUSPENDED: Administrator wants to\nsuspend the Audit
+SUSPENDED --> ONGOING: Administrator wants to\nresume the Audit
 FAILED --> DELETED : Administrator wants to\narchive/delete the Audit
 SUCCEEDED --> DELETED : Administrator wants to\narchive/delete the Audit
 PENDING --> CANCELLED : Administrator cancels\nthe Audit
 ONGOING --> CANCELLED : Administrator cancels\nthe Audit
 CANCELLED --> DELETED : Administrator wants to\narchive/delete the Audit
+SUSPENDED --> DELETED: Administrator wants to\narchive/delete the Audit
 DELETED --> [*]
 
 @enduml

doc/source/image_src/plantuml/sequence_overview_watcher_usage.txt

@@ -4,7 +4,7 @@ actor Administrator
 
 == Create some Audit settings ==
 
-Administrator -> Watcher : create new Audit Template (i.e. Audit settings : goal, scope, deadline,...)
+Administrator -> Watcher : create new Audit Template (i.e. Audit settings : goal, scope, ...)
 Watcher -> Watcher : save Audit Template in database
 Administrator <-- Watcher : Audit Template UUID
 

doc/source/image_src/plantuml/watcher_db_schema_diagram.txt

@@ -41,9 +41,7 @@ table(audit_templates) {
     uuid : String[36]
     name : String[63], nullable
     description : String[255], nullable
-    host_aggregate : Integer, nullable
-    extra : JSONEncodedDict
-    version : String[15], nullable
+    scope : JSONEncodedList
 
     created_at : DateTime
     updated_at : DateTime
@@ -59,10 +57,10 @@ table(audits) {
     uuid : String[36]
     audit_type : String[20]
     state : String[20], nullable
-    deadline : DateTime, nullable
     interval : Integer, nullable
     parameters : JSONEncodedDict, nullable
-    host_aggregate : Integer, nullable
+    scope : JSONEncodedList, nullable
+    auto_trigger: Boolean
 
     created_at : DateTime
     updated_at : DateTime
@@ -76,9 +74,8 @@ table(action_plans) {
     foreign_key("audit_id : Integer, nullable")
     foreign_key("strategy_id : Integer")
     uuid : String[36]
-    first_action_id : Integer
     state : String[20], nullable
-    global_efficacy : JSONEncodedDict, nullable
+    global_efficacy : JSONEncodedList, nullable
 
     created_at : DateTime
     updated_at : DateTime
@@ -94,7 +91,7 @@ table(actions) {
     action_type : String[255]
     input_parameters : JSONEncodedDict, nullable
     state : String[20], nullable
-    next : String[36], nullable
+    parents : JSONEncodedList, nullable
 
     created_at : DateTime
     updated_at : DateTime
@@ -131,6 +128,18 @@ table(scoring_engines) {
     deleted : Integer
 }
 
+table(service) {
+    primary_key(id: Integer)
+    name: String[255]
+    host: String[255]
+    last_seen_up: DateTime
+
+    created_at : DateTime
+    updated_at : DateTime
+    deleted_at : DateTime
+    deleted : Integer
+}
+
  "goals" <.. "strategies" : Foreign Key
  "goals" <.. "audit_templates" : Foreign Key
  "strategies" <.. "audit_templates" : Foreign Key

doc/source/index.rst

@@ -43,7 +43,7 @@ Introduction
 
   glossary
   architecture
-  dev/contributing
+  contributor/contributing
 
 
 Getting Started
@@ -52,12 +52,7 @@ Getting Started
 .. toctree::
   :maxdepth: 1
 
-  dev/environment
-  dev/devstack
-  deploy/configuration
-  deploy/conf-files
-  dev/testing
-  dev/rally_link
+  contributor/index
 
 API References
 --------------
@@ -65,7 +60,7 @@ API References
 .. toctree::
   :maxdepth: 1
 
-  webapi/v1
+  api/index
 
 Plugins
 -------
@@ -73,29 +68,38 @@ Plugins
 .. toctree::
   :maxdepth: 1
 
-  dev/plugin/base-setup
-  dev/plugin/goal-plugin
-  dev/plugin/scoring-engine-plugin
-  dev/plugin/strategy-plugin
-  dev/plugin/cdmc-plugin
-  dev/plugin/action-plugin
-  dev/plugin/planner-plugin
-  dev/plugins
+  contributor/plugin/index
 
+Installation
+============
+.. toctree::
+  :maxdepth: 2
+
+  install/index
+
+Watcher Configuration Options
+=============================
+
+.. toctree::
+  :maxdepth: 2
+
+  configuration/index
 
 Admin Guide
 ===========
 
-Introduction
-------------
+.. toctree::
+  :maxdepth: 2
+
+  admin/index
+
+User Guide
+==========
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
 
-  deploy/installation
-  deploy/user-guide
-  deploy/policy
-  deploy/gmr
+  user/index
 
 Watcher Manual Pages
 ====================
@@ -104,7 +108,7 @@ Watcher Manual Pages
    :glob:
    :maxdepth: 1
 
-   man/*
+   man/index
 
 .. # NOTE(mriedem): This is the section where we hide things that we don't
    # actually want in the table of contents but sphinx build would fail if

doc/source/install/common_configure.rst

@@ -0,0 +1,81 @@
+2. Edit the ``/etc/watcher/watcher.conf`` file and complete the following
+   actions:
+
+   * In the ``[database]`` section, configure database access:
+
+     .. code-block:: ini
+
+        [database]
+        ...
+        connection = mysql+pymysql://watcher:WATCHER_DBPASS@controller/watcher?charset=utf8
+
+   * In the `[DEFAULT]` section, configure the transport url for RabbitMQ message broker.
+
+     .. code-block:: ini
+
+        [DEFAULT]
+        ...
+        control_exchange = watcher
+        transport_url = rabbit://openstack:RABBIT_PASS@controller
+
+     Replace the RABBIT_PASS with the password you chose for OpenStack user in RabbitMQ.
+
+   * In the `[keystone_authtoken]` section, configure Identity service access.
+
+     .. code-block:: ini
+
+        [keystone_authtoken]
+        ...
+        auth_uri = http://controller:5000
+        auth_url = http://controller:35357
+        memcached_servers = controller:11211
+        auth_type = password
+        project_domain_name = default
+        user_domain_name = default
+        project_name = service
+        username = watcher
+        password = WATCHER_PASS
+
+     Replace WATCHER_PASS with the password you chose for the watcher user in the Identity service.
+
+   * Watcher interacts with other OpenStack projects via project clients, in order to instantiate these
+     clients, Watcher requests new session from Identity service. In the `[watcher_clients_auth]` section,
+     configure the identity service access to interact with other OpenStack project clients.
+
+     .. code-block:: ini
+
+        [watcher_clients_auth]
+        ...
+        auth_type = password
+        auth_url = http://controller:35357
+        username = watcher
+        password = WATCHER_PASS
+        project_domain_name = default
+        user_domain_name = default
+        project_name = service
+
+     Replace WATCHER_PASS with the password you chose for the watcher user in the Identity service.
+
+   * In the `[api]` section, configure host option.
+
+     .. code-block:: ini
+
+        [api]
+        ...
+        host = controller
+
+     Replace controller with the IP address of the management network interface on your controller node, typically 10.0.0.11 for the first node in the example architecture.
+
+   * In the `[oslo_messaging_notifications]` section, configure the messaging driver.
+
+     .. code-block:: ini
+
+        [oslo_messaging_notifications]
+        ...
+        driver = messagingv2
+
+3. Populate watcher database:
+
+   .. code-block:: ini
+
+     su -s /bin/sh -c "watcher-db-manage --config-file /etc/watcher/watcher.conf upgrade"

doc/source/install/common_prerequisites.rst

@@ -0,0 +1,139 @@
+Prerequisites
+-------------
+
+Before you install and configure the Infrastructure Optimization service,
+you must create a database, service credentials, and API endpoints.
+
+1. Create the database, complete these steps:
+
+   * Use the database access client to connect to the database
+     server as the ``root`` user:
+
+     .. code-block:: console
+
+        $ mysql -u root -p
+
+   * Create the ``watcher`` database:
+
+     .. code-block:: console
+
+        CREATE DATABASE watcher CHARACTER SET utf8;
+
+   * Grant proper access to the ``watcher`` database:
+
+     .. code-block:: console
+
+        GRANT ALL PRIVILEGES ON watcher.* TO 'watcher'@'localhost' \
+          IDENTIFIED BY 'WATCHER_DBPASS';
+        GRANT ALL PRIVILEGES ON watcher.* TO 'watcher'@'%' \
+          IDENTIFIED BY 'WATCHER_DBPASS';
+
+     Replace ``WATCHER_DBPASS`` with a suitable password.
+
+   * Exit the database access client.
+
+     .. code-block:: console
+
+        exit;
+
+2. Source the ``admin`` credentials to gain access to
+   admin-only CLI commands:
+
+   .. code-block:: console
+
+      $ . admin-openrc
+
+3. To create the service credentials, complete these steps:
+
+   * Create the ``watcher`` user:
+
+     .. code-block:: console
+
+        $ openstack user create --domain default --password-prompt watcher
+          User Password:
+          Repeat User Password:
+          +---------------------+----------------------------------+
+          | Field               | Value                            |
+          +---------------------+----------------------------------+
+          | domain_id           | default                          |
+          | enabled             | True                             |
+          | id                  | b18ee38e06034b748141beda8fc8bfad |
+          | name                | watcher                          |
+          | options             | {}                               |
+          | password_expires_at | None                             |
+          +---------------------+----------------------------------+
+
+
+   * Add the ``admin`` role to the ``watcher`` user:
+
+     .. code-block:: console
+
+        $ openstack role add --project service --user watcher admin
+
+     .. note::
+
+        This command produces no output.
+
+   * Create the watcher service entities:
+
+     .. code-block:: console
+
+        $ openstack service create --name watcher --description "Infrastructure Optimization" infra-optim
+          +-------------+----------------------------------+
+          | Field       | Value                            |
+          +-------------+----------------------------------+
+          | description | Infrastructure Optimization      |
+          | enabled     | True                             |
+          | id          | d854f6fff0a64f77bda8003c8dedfada |
+          | name        | watcher                          |
+          | type        | infra-optim                      |
+          +-------------+----------------------------------+
+
+
+4. Create the Infrastructure Optimization service API endpoints:
+
+   .. code-block:: console
+
+      $ openstack endpoint create --region RegionOne \
+        infra-optim public http://controller:9322
+        +-------------+----------------------------------+
+        | Field       | Value                            |
+        +-------------+----------------------------------+
+        | description | Infrastructure Optimization      |
+        | enabled     | True                             |
+        | id          | d854f6fff0a64f77bda8003c8dedfada |
+        | name        | watcher                          |
+        | type        | infra-optim                      |
+        +-------------+----------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        infra-optim internal http://controller:9322
+        +--------------+----------------------------------+
+        | Field        | Value                            |
+        +--------------+----------------------------------+
+        | enabled      | True                             |
+        | id           | 225aef8465ef4df48a341aaaf2b0a390 |
+        | interface    | internal                         |
+        | region       | RegionOne                        |
+        | region_id    | RegionOne                        |
+        | service_id   | d854f6fff0a64f77bda8003c8dedfada |
+        | service_name | watcher                          |
+        | service_type | infra-optim                      |
+        | url          | http://controller:9322           |
+        +--------------+----------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        infra-optim admin http://controller:9322
+        +--------------+----------------------------------+
+        | Field        | Value                            |
+        +--------------+----------------------------------+
+        | enabled      | True                             |
+        | id           | 375eb5057fb546edbdf3ee4866179672 |
+        | interface    | admin                            |
+        | region       | RegionOne                        |
+        | region_id    | RegionOne                        |
+        | service_id   | d854f6fff0a64f77bda8003c8dedfada |
+        | service_name | watcher                          |
+        | service_type | infra-optim                      |
+        | url          | http://controller:9322           |
+        +--------------+----------------------------------+

doc/source/install/get_started.rst

@@ -0,0 +1,27 @@
+============================================
+Infrastructure Optimization service overview
+============================================
+The Infrastructure Optimization service provides flexible and scalable
+optimization service for multi-tenant OpenStack based clouds.
+
+The Infrastructure Optimization service consists of the following components:
+
+``watcher`` command-line client
+  A CLI to communicate with ``watcher-api`` to optimize the cloud.
+
+``watcher-api`` service
+  An OpenStack-native REST API that accepts and responds to end-user calls
+  by processing them and forwarding to appropriate underlying watcher
+  services via AMQP.
+
+``watcher-decision-engine`` service
+  It runs audit and return an action plan to achieve optimization goal
+  specified by the end-user in audit.
+
+``watcher-applier`` service
+  It executes action plan built by watcher-decision-engine. It interacts with
+  other OpenStack components like nova to execute the given action
+  plan.
+
+``watcher-dashboard``
+  Watcher UI implemented as a plugin for the OpenStack Dashboard.

doc/source/install/index.rst

@@ -0,0 +1,39 @@
+===================================
+Infrastructure Optimization service
+===================================
+
+.. toctree::
+   :maxdepth: 2
+
+   get_started.rst
+   install.rst
+   verify.rst
+   next-steps.rst
+
+The Infrastructure Optimization service (watcher) provides
+flexible and scalable resource optimization service for
+multi-tenant OpenStack-based clouds.
+
+Watcher provides a complete optimization loop including
+everything from a metrics receiver, complex event processor
+and profiler, optimization processor and an action plan
+applier. This provides a robust framework to realize a wide
+range of cloud optimization goals, including the reduction
+of data center operating costs, increased system performance
+via intelligent virtual machine migration, increased energy
+efficiency—and more!
+
+Watcher also supports a pluggable architecture by which custom
+optimization algorithms, data metrics and data profilers can be
+developed and inserted into the Watcher framework.
+
+Check the documentation for watcher optimization strategies at
+https://docs.openstack.org/watcher/latest/strategies/index.html
+
+Check watcher glossary at
+https://docs.openstack.org/watcher/latest/glossary.html
+
+
+This chapter assumes a working setup of OpenStack following the
+`OpenStack Installation Tutorial
+<https://docs.openstack.org/pike/install/>`_.

doc/source/install/install-rdo.rst

@@ -0,0 +1,38 @@
+.. _install-rdo:
+
+Install and configure for Red Hat Enterprise Linux and CentOS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+This section describes how to install and configure the Infrastructure
+Optimization service for Red Hat Enterprise Linux 7 and CentOS 7.
+
+.. include:: common_prerequisites.rst
+
+Install and configure components
+--------------------------------
+
+1. Install the packages:
+
+   .. code-block:: console
+
+      # sudo yum install openstack-watcher-api openstack-watcher-applier \
+        openstack-watcher-decision-engine
+
+.. include:: common_configure.rst
+
+Finalize installation
+---------------------
+
+Start the Infrastructure Optimization services and configure them to start when
+the system boots:
+
+.. code-block:: console
+
+   # systemctl enable openstack-watcher-api.service \
+     openstack-watcher-decision-engine.service \
+     openstack-watcher-applier.service
+
+   # systemctl start openstack-watcher-api.service \
+     openstack-watcher-decision-engine.service \
+     openstack-watcher-applier.service

doc/source/install/install-ubuntu.rst

@@ -0,0 +1,34 @@
+.. _install-ubuntu:
+
+Install and configure for Ubuntu
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes how to install and configure the Infrastructure
+Optimization service for Ubuntu 14.04 (LTS).
+
+.. include:: common_prerequisites.rst
+
+Install and configure components
+--------------------------------
+
+1. Install the packages:
+
+   .. code-block:: console
+
+      # apt install watcher-api watcher-decision-engine \
+        watcher-applier
+
+      # apt install python-watcherclient
+
+.. include:: common_configure.rst
+
+Finalize installation
+---------------------
+
+Restart the Infrastructure Optimization services:
+
+.. code-block:: console
+
+   # service watcher-api restart
+   # service watcher-decision-engine restart
+   # service watcher-applier restart

doc/source/install/install.rst

@@ -0,0 +1,19 @@
+.. _install:
+
+Install and configure
+~~~~~~~~~~~~~~~~~~~~~
+
+This section describes how to install and configure the Infrastructure
+Optimization service, code-named watcher, on the controller node.
+
+This section assumes that you already have a working OpenStack
+environment with at least the following components installed:
+Identity Service, Compute Service, Telemetry data collection service.
+
+Note that installation and configuration vary by distribution.
+
+.. toctree::
+   :maxdepth: 2
+
+   install-rdo.rst
+   install-ubuntu.rst

doc/source/install/next-steps.rst

@@ -0,0 +1,9 @@
+.. _next-steps:
+
+Next steps
+~~~~~~~~~~
+
+Your OpenStack environment now includes the watcher service.
+
+To add additional services, see
+https://docs.openstack.org/pike/install/.

doc/source/install/verify.rst

@@ -0,0 +1,119 @@
+.. _verify:
+
+Verify operation
+~~~~~~~~~~~~~~~~
+
+Verify operation of the Infrastructure Optimization service.
+
+.. note::
+
+   Perform these commands on the controller node.
+
+1. Source the ``admin`` project credentials to gain access to
+   admin-only CLI commands:
+
+   .. code-block:: console
+
+      $ . admin-openrc
+
+2. List service components to verify successful launch and registration
+   of each process:
+
+   .. code-block:: console
+
+      $ openstack optimize service list
+        +----+-------------------------+------------+--------+
+        | ID | Name                    | Host       | Status |
+        +----+-------------------------+------------+--------+
+        |  1 | watcher-decision-engine | controller | ACTIVE |
+        |  2 | watcher-applier         | controller | ACTIVE |
+        +----+-------------------------+------------+--------+
+
+3. List goals and strategies:
+
+   .. code-block:: console
+
+      $ openstack optimize goal list
+        +--------------------------------------+----------------------+----------------------+
+        | UUID                                 | Name                 | Display name         |
+        +--------------------------------------+----------------------+----------------------+
+        | a8cd6d1a-008b-4ff0-8dbc-b30493fcc5b9 | dummy                | Dummy goal           |
+        | 03953f2f-02d0-42b5-9a12-7ba500a54395 | workload_balancing   | Workload Balancing   |
+        | de0f8714-984b-4d6b-add1-9cad8120fbce | server_consolidation | Server Consolidation |
+        | f056bc80-c6d1-40dc-b002-938ccade9385 | thermal_optimization | Thermal Optimization |
+        | e7062856-892e-4f0f-b84d-b828464b3fd0 | airflow_optimization | Airflow Optimization |
+        | 1f038da9-b36c-449f-9f04-c225bf3eb478 | unclassified         | Unclassified         |
+        +--------------------------------------+----------------------+----------------------+
+
+      $ openstack optimize strategy list
+      +--------------------------------------+---------------------------+---------------------------------------------+----------------------+
+      | UUID                                 | Name                      | Display name                                | Goal                 |
+      +--------------------------------------+---------------------------+---------------------------------------------+----------------------+
+      | 98ae84c8-7c9b-4cbd-8d9c-4bd7c6b106eb | dummy                     | Dummy strategy                              | dummy                |
+      | 02a170b6-c72e-479d-95c0-8a4fdd4cc1ef | dummy_with_scorer         | Dummy Strategy using sample Scoring Engines | dummy                |
+      | 8bf591b8-57e5-4a9e-8c7d-c37bda735a45 | outlet_temperature        | Outlet temperature based strategy           | thermal_optimization |
+      | 8a0810fb-9d9a-47b9-ab25-e442878abc54 | vm_workload_consolidation | VM Workload Consolidation Strategy          | server_consolidation |
+      | 1718859c-3eb5-45cb-9220-9cb79fe42fa5 | basic                     | Basic offline consolidation                 | server_consolidation |
+      | b5e7f5f1-4824-42c7-bb52-cf50724f67bf | workload_stabilization    | Workload stabilization                      | workload_balancing   |
+      | f853d71e-9286-4df3-9d3e-8eaf0f598e07 | workload_balance          | Workload Balance Migration Strategy         | workload_balancing   |
+      | 58bdfa89-95b5-4630-adf6-fd3af5ff1f75 | uniform_airflow           | Uniform airflow migration strategy          | airflow_optimization |
+      | 66fde55d-a612-4be9-8cb0-ea63472b420b | dummy_with_resize         | Dummy strategy with resize                  | dummy                |
+      +--------------------------------------+---------------------------+---------------------------------------------+----------------------+
+
+4. Run an action plan by creating an audit with dummy goal:
+
+   .. code-block:: console
+
+      $ openstack optimize audit create --goal dummy
+        +--------------+--------------------------------------+
+        | Field        | Value                                |
+        +--------------+--------------------------------------+
+        | UUID         | e94d4826-ad4e-44df-ad93-dff489fde457 |
+        | Created At   | 2017-05-23T11:46:58.763394+00:00     |
+        | Updated At   | None                                 |
+        | Deleted At   | None                                 |
+        | State        | PENDING                              |
+        | Audit Type   | ONESHOT                              |
+        | Parameters   | {}                                   |
+        | Interval     | None                                 |
+        | Goal         | dummy                                |
+        | Strategy     | auto                                 |
+        | Audit Scope  | []                                   |
+        | Auto Trigger | False                                |
+        +--------------+--------------------------------------+
+
+      $ openstack optimize audit list
+        +--------------------------------------+------------+-----------+-------+----------+--------------+
+        | UUID                                 | Audit Type | State     | Goal  | Strategy | Auto Trigger |
+        +--------------------------------------+------------+-----------+-------+----------+--------------+
+        | e94d4826-ad4e-44df-ad93-dff489fde457 | ONESHOT    | SUCCEEDED | dummy | auto     | False        |
+        +--------------------------------------+------------+-----------+-------+----------+--------------+
+
+      $ openstack optimize actionplan list
+        +--------------------------------------+--------------------------------------+-------------+------------+-----------------+
+        | UUID                                 | Audit                                | State       | Updated At | Global efficacy |
+        +--------------------------------------+--------------------------------------+-------------+------------+-----------------+
+        | ba9ce6b3-969c-4b8e-bb61-ae24e8630f81 | e94d4826-ad4e-44df-ad93-dff489fde457 | RECOMMENDED | None       | None            |
+        +--------------------------------------+--------------------------------------+-------------+------------+-----------------+
+
+     $ openstack optimize actionplan start ba9ce6b3-969c-4b8e-bb61-ae24e8630f81
+       +---------------------+--------------------------------------+
+       | Field               | Value                                |
+       +---------------------+--------------------------------------+
+       | UUID                | ba9ce6b3-969c-4b8e-bb61-ae24e8630f81 |
+       | Created At          | 2017-05-23T11:46:58+00:00            |
+       | Updated At          | 2017-05-23T11:53:12+00:00            |
+       | Deleted At          | None                                 |
+       | Audit               | e94d4826-ad4e-44df-ad93-dff489fde457 |
+       | Strategy            | dummy                                |
+       | State               | ONGOING                              |
+       | Efficacy indicators | []                                   |
+       | Global efficacy     | {}                                   |
+       +---------------------+--------------------------------------+
+
+     $ openstack optimize actionplan list
+     +--------------------------------------+--------------------------------------+-----------+---------------------------+-----------------+
+     | UUID                                 | Audit                                | State     | Updated At                | Global efficacy |
+     +--------------------------------------+--------------------------------------+-----------+---------------------------+-----------------+
+     | ba9ce6b3-969c-4b8e-bb61-ae24e8630f81 | e94d4826-ad4e-44df-ad93-dff489fde457 | SUCCEEDED | 2017-05-23T11:53:16+00:00 | None            |
+     +--------------------------------------+--------------------------------------+-----------+---------------------------+-----------------+

doc/source/man/index.rst

@@ -0,0 +1,8 @@
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   watcher-api
+   watcher-applier
+   watcher-db-manage
+   watcher-decision-engine

doc/source/strategies/basic-server-consolidation.rst

@@ -0,0 +1,99 @@
+==================================
+Basic Offline Server Consolidation
+==================================
+
+Synopsis
+--------
+
+**display name**: ``Basic offline consolidation``
+
+**goal**: ``server_consolidation``
+
+    .. watcher-term:: watcher.decision_engine.strategy.strategies.basic_consolidation
+
+Requirements
+------------
+
+Metrics
+*******
+
+The *basic* strategy requires the following metrics:
+
+============================ ============ ======= =======
+metric                       service name plugins comment
+============================ ============ ======= =======
+``compute.node.cpu.percent`` ceilometer_  none
+``cpu_util``                 ceilometer_  none
+============================ ============ ======= =======
+
+.. _ceilometer: https://docs.openstack.org/ceilometer/latest/admin/telemetry-measurements.html#openstack-compute
+
+Cluster data model
+******************
+
+Default Watcher's Compute cluster data model:
+
+    .. watcher-term:: watcher.decision_engine.model.collector.nova.NovaClusterDataModelCollector
+
+Actions
+*******
+
+Default Watcher's actions:
+
+
+    .. list-table::
+       :widths: 30 30
+       :header-rows: 1
+
+       * - action
+         - description
+       * - ``migration``
+         - .. watcher-term:: watcher.applier.actions.migration.Migrate
+       * - ``change_nova_service_state``
+         - .. watcher-term:: watcher.applier.actions.change_nova_service_state.ChangeNovaServiceState
+
+Planner
+*******
+
+Default Watcher's planner:
+
+    .. watcher-term:: watcher.decision_engine.planner.weight.WeightPlanner
+
+Configuration
+-------------
+
+Strategy parameter is:
+
+====================== ====== ============= ===================================
+parameter              type   default Value description
+====================== ====== ============= ===================================
+``migration_attempts`` Number 0             Maximum number of combinations to
+                                            be tried by the strategy while
+                                            searching for potential candidates.
+                                            To remove the limit, set it to 0
+``period``             Number 7200          The time interval in seconds
+                                            for getting statistic aggregation
+                                            from metric data source
+====================== ====== ============= ===================================
+
+Efficacy Indicator
+------------------
+
+.. watcher-func::
+  :format: literal_block
+
+  watcher.decision_engine.goal.efficacy.specs.ServerConsolidation.get_global_efficacy_indicator
+
+How to use it ?
+---------------
+
+.. code-block:: shell
+
+    $ openstack optimize audittemplate create \
+      at1 server_consolidation --strategy basic
+
+    $ openstack optimize audit create -a at1 -p migration_attempts=4
+
+External Links
+--------------
+None.

doc/source/strategies/index.rst

@@ -0,0 +1,8 @@
+Strategies
+==========
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   ./*

doc/source/strategies/outlet_temp_control.rst

@@ -0,0 +1,104 @@
+=================================
+Outlet Temperature Based Strategy
+=================================
+
+Synopsis
+--------
+
+**display name**: ``Outlet temperature based strategy``
+
+**goal**: ``thermal_optimization``
+
+Outlet (Exhaust Air) temperature is a new thermal telemetry which can be
+used to measure the host's thermal/workload status. This strategy makes
+decisions to migrate workloads to the hosts with good thermal condition
+(lowest outlet temperature) when the outlet temperature of source hosts
+reach a configurable threshold.
+
+Requirements
+------------
+
+This strategy has a dependency on the host having Intel's Power
+Node Manager 3.0 or later enabled.
+
+
+Metrics
+*******
+
+The *outlet_temperature* strategy requires the following metrics:
+
+========================================= ============ ======= =======
+metric                                    service name plugins comment
+========================================= ============ ======= =======
+``hardware.ipmi.node.outlet_temperature`` ceilometer_  IPMI
+========================================= ============ ======= =======
+
+.. _ceilometer: https://docs.openstack.org/ceilometer/latest/admin/telemetry-measurements.html#ipmi-based-meters
+
+Cluster data model
+******************
+
+Default Watcher's Compute cluster data model:
+
+    .. watcher-term:: watcher.decision_engine.model.collector.nova.NovaClusterDataModelCollector
+
+Actions
+*******
+
+Default Watcher's actions:
+
+    .. list-table::
+       :widths: 30 30
+       :header-rows: 1
+
+       * - action
+         - description
+       * - ``migration``
+         - .. watcher-term:: watcher.applier.actions.migration.Migrate
+
+Planner
+*******
+
+Default Watcher's planner:
+
+    .. watcher-term:: watcher.decision_engine.planner.weight.WeightPlanner
+
+Configuration
+-------------
+
+Strategy parameter is:
+
+============== ====== ============= ====================================
+parameter      type   default Value description
+============== ====== ============= ====================================
+``threshold``  Number 35.0          Temperature threshold for migration
+``period``     Number 30            The time interval in seconds for
+                                    getting statistic aggregation from
+                                    metric data source
+============== ====== ============= ====================================
+
+Efficacy Indicator
+------------------
+
+None
+
+Algorithm
+---------
+
+For more information on the Outlet Temperature Based Strategy please refer to:
+https://specs.openstack.org/openstack/watcher-specs/specs/mitaka/implemented/outlet-temperature-based-strategy.html
+
+How to use it ?
+---------------
+
+.. code-block:: shell
+
+    $ openstack optimize audittemplate create \
+      at1 thermal_optimization --strategy outlet_temperature
+
+    $ openstack optimize audit create -a at1 -p threshold=31.0
+
+External Links
+--------------
+
+- `Intel Power Node Manager 3.0 <http://www.intel.com/content/www/us/en/power-management/intelligent-power-node-manager-3-0-specification.html>`_