Added efficacy specification to /goals

In this changeset, I added the new Efficacy, EfficacySpecification
and IndicatorSpecification classes which are the main components for
computing an efficacy.

Partially Implements: blueprint efficacy-indicator

Change-Id: I3a1d62569de2dd6bb6f9a52f6058313fa2b886ce

watcher/decision_engine/goal/base.py

@@ -31,6 +31,7 @@ class Goal(loadable.Loadable):
         super(Goal, self).__init__(config)
         self.name = self.get_name()
         self.display_name = self.get_display_name()
+        self.efficacy_specification = self.get_efficacy_specification()
 
     @classmethod
     @abc.abstractmethod
@@ -60,3 +61,8 @@ class Goal(loadable.Loadable):
         :rtype: list of :class:`oslo_config.cfg.Opt` instances
         """
         return []
+
+    @abc.abstractmethod
+    def get_efficacy_specification(cls):
+        """The efficacy spec for the current goal"""
+        raise NotImplementedError()

watcher/decision_engine/goal/efficacy/base.py

@@ -0,0 +1,75 @@
+# -*- encoding: utf-8 -*-
+# Copyright (c) 2016 b<>com
+#
+# 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.
+
+import abc
+import json
+
+import six
+import voluptuous
+
+
+@six.add_metaclass(abc.ABCMeta)
+class EfficacySpecification(object):
+
+    def __init__(self):
+        self._indicators_specs = self.get_indicators_specifications()
+
+    @property
+    def indicators_specs(self):
+        return self._indicators_specs
+
+    @abc.abstractmethod
+    def get_indicators_specifications(self):
+        """List the specifications of the indicator for this efficacy spec
+
+        :return: Tuple of indicator specifications
+        :rtype: Tuple of :py:class:`~.IndicatorSpecification` instances
+        """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def get_global_efficacy_indicator(self, indicators_map):
+        """Compute the global efficacy for the goal it achieves
+
+        :param indicators_map: dict-like object containing the
+                               efficacy indicators related to this spec
+        :type indicators_map: :py:class:`~.IndicatorsMap` instance
+        :raises: NotImplementedError
+        :returns: :py:class:`~.Indicator` instance
+        """
+        raise NotImplementedError()
+
+    @property
+    def schema(self):
+        """Combined schema from the schema of the indicators"""
+        schema = voluptuous.Schema({}, required=True)
+        for indicator in self.indicators_specs:
+            key_constraint = (voluptuous.Required
+                              if indicator.required else voluptuous.Optional)
+            schema = schema.extend(
+                {key_constraint(indicator.name): indicator.schema.schema})
+
+        return schema
+
+    def validate_efficacy_indicators(self, indicators_map):
+        return self.schema(indicators_map)
+
+    def get_indicators_specs_dicts(self):
+        return [indicator.to_dict()
+                for indicator in self.indicators_specs]
+
+    def serialize_indicators_specs(self):
+        return json.dumps(self.get_indicators_specs_dicts())

watcher/decision_engine/goal/efficacy/indicators.py

@@ -0,0 +1,132 @@
+# -*- encoding: utf-8 -*-
+# Copyright (c) 2016 b<>com
+#
+# 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.
+
+import abc
+import six
+
+from oslo_log import log
+import voluptuous
+
+from watcher._i18n import _
+from watcher.common import exception
+
+LOG = log.getLogger(__name__)
+
+
+@six.add_metaclass(abc.ABCMeta)
+class IndicatorSpecification(object):
+
+    def __init__(self, name=None, description=None, unit=None, required=True):
+        self.name = name
+        self.description = description
+        self.unit = unit
+        self.required = required
+
+    @abc.abstractproperty
+    def schema(self):
+        """Schema used to validate the indicator value
+
+        :return: A Voplutuous Schema
+        :rtype: :py:class:`.voluptuous.Schema` instance
+        """
+        raise NotImplementedError()
+
+    @classmethod
+    def validate(cls, solution):
+        """Validate the given solution
+
+        :raises: :py:class:`~.InvalidIndicatorValue` when the validation fails
+        """
+        indicator = cls()
+        value = None
+        try:
+            value = getattr(solution, indicator.name)
+            indicator.schema(value)
+        except Exception as exc:
+            LOG.exception(exc)
+            raise exception.InvalidIndicatorValue(
+                name=indicator.name, value=value, spec_type=type(indicator))
+
+    def to_dict(self):
+        return {
+            "name": self.name,
+            "description": self.description,
+            "unit": self.unit,
+            "schema": str(self.schema.schema) if self.schema else None,
+        }
+
+    def __str__(self):
+        return str(self.to_dict())
+
+
+class AverageCpuLoad(IndicatorSpecification):
+
+    def __init__(self):
+        super(AverageCpuLoad, self).__init__(
+            name="avg_cpu_percent",
+            description=_("Average CPU load as a percentage of the CPU time."),
+            unit="%",
+        )
+
+    @property
+    def schema(self):
+        return voluptuous.Schema(
+            voluptuous.Range(min=0, max=100), required=True)
+
+
+class MigrationEfficacy(IndicatorSpecification):
+
+    def __init__(self):
+        super(MigrationEfficacy, self).__init__(
+            name="migration_efficacy",
+            description=_("Represents the percentage of released nodes out of "
+                          "the total number of migrations."),
+            unit="%",
+            required=True
+        )
+
+    @property
+    def schema(self):
+        return voluptuous.Schema(
+            voluptuous.Range(min=0, max=100), required=True)
+
+
+class ReleasedComputeNodesCount(IndicatorSpecification):
+    def __init__(self):
+        super(ReleasedComputeNodesCount, self).__init__(
+            name="released_compute_nodes_count",
+            description=_("The number of compute nodes to be released."),
+            unit=None,
+        )
+
+    @property
+    def schema(self):
+        return voluptuous.Schema(
+            voluptuous.Range(min=0), required=True)
+
+
+class VmMigrationsCount(IndicatorSpecification):
+    def __init__(self):
+        super(VmMigrationsCount, self).__init__(
+            name="vm_migrations_count",
+            description=_("The number of migrations to be performed."),
+            unit=None,
+        )
+
+    @property
+    def schema(self):
+        return voluptuous.Schema(
+            voluptuous.Range(min=0), required=True)

watcher/decision_engine/goal/efficacy/specs.py

@@ -0,0 +1,52 @@
+# -*- encoding: utf-8 -*-
+# Copyright (c) 2016 b<>com
+#
+# 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.
+
+from watcher._i18n import _
+from watcher.decision_engine.goal.efficacy import base
+from watcher.decision_engine.goal.efficacy import indicators
+from watcher.decision_engine.solution import efficacy
+
+
+class Unclassified(base.EfficacySpecification):
+
+    def get_indicators_specifications(self):
+        return ()
+
+    def get_global_efficacy_indicator(self, indicators_map):
+        return None
+
+
+class ServerConsolidation(base.EfficacySpecification):
+
+    def get_indicators_specifications(self):
+        return [
+            indicators.ReleasedComputeNodesCount(),
+            indicators.VmMigrationsCount(),
+        ]
+
+    def get_global_efficacy_indicator(self, indicators_map):
+        value = 0
+        if indicators_map.vm_migrations_count > 0:
+            value = (float(indicators_map.released_compute_nodes_count) /
+                     float(indicators_map.vm_migrations_count)) * 100
+
+        return efficacy.Indicator(
+            name="released_nodes_ratio",
+            description=_("Ratio of released compute nodes divided by the "
+                          "number of VM migrations."),
+            unit='%',
+            value=value,
+        )

watcher/decision_engine/goal/goals.py

@@ -16,9 +16,14 @@
 
 from watcher._i18n import _
 from watcher.decision_engine.goal import base
+from watcher.decision_engine.goal.efficacy import specs
 
 
 class Dummy(base.Goal):
+    """Dummy
+
+    Reserved goal that is used for testing purposes.
+    """
 
     @classmethod
     def get_name(cls):
@@ -32,8 +37,21 @@ class Dummy(base.Goal):
     def get_translatable_display_name(cls):
         return "Dummy goal"
 
+    @classmethod
+    def get_efficacy_specification(cls):
+        """The efficacy spec for the current goal"""
+        return specs.Unclassified()
+
 
 class Unclassified(base.Goal):
+    """Unclassified
+
+    This goal is used to ease the development process of a strategy. Containing
+    no actual indicator specification, this goal can be used whenever a
+    strategy has yet to be formally associated with an existing goal. If the
+    goal achieve has been identified but there is no available implementation,
+    this Goal can also be used as a transitional stage.
+    """
 
     @classmethod
     def get_name(cls):
@@ -47,6 +65,11 @@ class Unclassified(base.Goal):
     def get_translatable_display_name(cls):
         return "Unclassified"
 
+    @classmethod
+    def get_efficacy_specification(cls):
+        """The efficacy spec for the current goal"""
+        return specs.Unclassified()
+
 
 class ServerConsolidation(base.Goal):
 
@@ -62,6 +85,11 @@ class ServerConsolidation(base.Goal):
     def get_translatable_display_name(cls):
         return "Server consolidation"
 
+    @classmethod
+    def get_efficacy_specification(cls):
+        """The efficacy spec for the current goal"""
+        return specs.ServerConsolidation()
+
 
 class ThermalOptimization(base.Goal):
 
@@ -77,6 +105,11 @@ class ThermalOptimization(base.Goal):
     def get_translatable_display_name(cls):
         return "Thermal optimization"
 
+    @classmethod
+    def get_efficacy_specification(cls):
+        """The efficacy spec for the current goal"""
+        return specs.Unclassified()
+
 
 class WorkloadBalancing(base.Goal):
 
@@ -91,3 +124,8 @@ class WorkloadBalancing(base.Goal):
     @classmethod
     def get_translatable_display_name(cls):
         return "Workload balancing"
+
+    @classmethod
+    def get_efficacy_specification(cls):
+        """The efficacy spec for the current goal"""
+        return specs.Unclassified()

watcher/decision_engine/solution/efficacy.py

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+# Copyright (c) 2016 b<>com
+#
+# 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.
+
+from watcher.common import utils
+
+
+class Indicator(utils.Struct):
+
+    def __init__(self, name, description, unit, value):
+        super(Indicator, self).__init__()
+        self.name = name
+        self.description = description
+        self.unit = unit
+        self.value = value

watcher/decision_engine/sync.py

@@ -26,7 +26,7 @@ from watcher import objects
 LOG = log.getLogger(__name__)
 
 GoalMapping = collections.namedtuple(
-    'GoalMapping', ['name', 'display_name'])
+    'GoalMapping', ['name', 'display_name', 'efficacy_specification'])
 StrategyMapping = collections.namedtuple(
     'StrategyMapping', ['name', 'goal_name', 'display_name'])
 
@@ -75,7 +75,10 @@ class Syncer(object):
             self._available_goals_map = {
                 GoalMapping(
                     name=g.name,
-                    display_name=g.display_name): g
+                    display_name=g.display_name,
+                    efficacy_specification=tuple(
+                        IndicatorSpec(**item)
+                        for item in g.efficacy_specification)): g
                 for g in self.available_goals
             }
         return self._available_goals_map
@@ -127,6 +130,9 @@ class Syncer(object):
             goal = objects.Goal(self.ctx)
             goal.name = goal_name
             goal.display_name = goal_map.display_name
+            goal.efficacy_specification = [
+                indicator._asdict()
+                for indicator in goal_map.efficacy_specification]
             goal.create()
             LOG.info(_LI("Goal %s created"), goal_name)
 
@@ -140,6 +146,7 @@ class Syncer(object):
 
     def _sync_strategy(self, strategy_map):
         strategy_name = strategy_map.name
+        strategy_display_name = strategy_map.display_name
         goal_name = strategy_map.goal_name
         strategy_mapping = dict()
 
@@ -153,7 +160,7 @@ class Syncer(object):
         if stale_strategies or not matching_strategies:
             strategy = objects.Strategy(self.ctx)
             strategy.name = strategy_name
-            strategy.display_name = strategy_map.display_name
+            strategy.display_name = strategy_display_name
             strategy.goal_id = objects.Goal.get_by_name(self.ctx, goal_name).id
             strategy.create()
             LOG.info(_LI("Strategy %s created"), strategy_name)
@@ -267,7 +274,11 @@ class Syncer(object):
         for _, goal_cls in implemented_goals.items():
             goals_map[goal_cls.get_name()] = GoalMapping(
                 name=goal_cls.get_name(),
-                display_name=goal_cls.get_translatable_display_name())
+                display_name=goal_cls.get_translatable_display_name(),
+                efficacy_specification=tuple(
+                    IndicatorSpec(**indicator.to_dict())
+                    for indicator in goal_cls.get_efficacy_specification()
+                                             .get_indicators_specifications()))
 
         for _, strategy_cls in implemented_strategies.items():
             strategies_map[strategy_cls.get_name()] = StrategyMapping(
@@ -289,10 +300,12 @@ class Syncer(object):
         """
         goal_display_name = goal_map.display_name
         goal_name = goal_map.name
+        goal_efficacy_spec = goal_map.efficacy_specification
 
         stale_goals = []
         for matching_goal in matching_goals:
-            if matching_goal.display_name == goal_display_name:
+            if (matching_goal.efficacy_specification == goal_efficacy_spec and
+                    matching_goal.display_name == goal_display_name):
                 LOG.info(_LI("Goal %s unchanged"), goal_name)
             else:
                 LOG.info(_LI("Goal %s modified"), goal_name)