Documentation on goal and efficacy

In this changeset, I wrote a documentation detailing how one can
implement a new goal plugin. I also mention to define the efficacy
specification for a given goal.

Partially Implements: blueprint efficacy-indicator

Change-Id: Iba267ae312f248b49d4600504f11678cdc225622

doc/source/image_src/plantuml/sequence_from_audit_execution_to_actionplan_creation.txt

@@ -0,0 +1,44 @@
+@startuml
+
+skinparam maxMessageSize 200
+
+"Decision Engine" -> "Decision Engine" : Execute audit
+activate "Decision Engine"
+"Decision Engine" -> "Decision Engine" : Set the audit state to ONGOING
+
+"Decision Engine" -> "Strategy selector" : Select strategy
+activate "Strategy selector"
+alt A specific strategy is provided
+"Strategy selector" -> "Strategy selector" : Load strategy and inject the \
+cluster data model
+else Only a goal is specified
+"Strategy selector" -> "Strategy selector" : select strategy
+"Strategy selector" -> "Strategy selector" : Load strategy and inject the \
+cluster data model
+end
+"Strategy selector" -> "Decision Engine" : Return loaded Strategy
+deactivate "Strategy selector"
+
+"Decision Engine" -> "Strategy" : Execute the strategy
+activate "Strategy"
+"Strategy" -> "Strategy" : **pre_execute()**Checks if the strategy \
+pre-requisites are all set.
+"Strategy" -> "Strategy" : **do_execute()**Contains the logic of the strategy
+"Strategy" -> "Strategy" : **post_execute()** Set the efficacy indicators
+"Strategy" -> "Strategy" : Compute the global efficacy of the solution \
+based on the provided efficacy indicators
+"Strategy" -> "Decision Engine" : Return the solution
+deactivate "Strategy"
+
+"Decision Engine" -> "Planner" : Plan the solution that was computed by the \
+strategy
+activate "Planner"
+"Planner" -> "Planner" : Store the planned solution as an action plan with its \
+related actions and efficacy indicators
+"Planner" --> "Decision Engine" : Done
+deactivate "Planner"
+"Decision Engine" -> "Decision Engine" : Update the audit state to SUCCEEDED
+
+deactivate "Decision Engine"
+
+@enduml

doc/source/image_src/plantuml/sequence_trigger_audit_in_decision_engine.txt

@@ -1,31 +1,54 @@
 @startuml
 
-"AMQP Bus" -> "Watcher Decision Engine"  : trigger_audit(new_audit.uuid)
-"Watcher Decision Engine" -> "Watcher Database" : update audit.state = ONGOING
-"AMQP Bus" <[#blue]- "Watcher Decision Engine" : notify new audit state = ONGOING
-"Watcher Decision Engine" -> "Watcher Database" : get audit parameters(goal, ...)
-"Watcher Decision Engine" <-- "Watcher Database" : audit parameters(goal, ...)
+skinparam maxMessageSize 100
+
+"AMQP Bus" -> "Decision Engine"  : trigger audit
+
+activate "Decision Engine"
+
+"Decision Engine" -> "Database" : update audit.state = ONGOING
+"AMQP Bus" <[#blue]- "Decision Engine" : notify new audit state = ONGOING
+"Decision Engine" -> "Database" : get audit parameters (goal, strategy, ...)
+"Decision Engine" <-- "Database" : audit parameters (goal, strategy, ...)
+"Decision Engine" --> "Decision Engine": select appropriate \
+optimization strategy (via the Strategy Selector)
 create Strategy
-"Watcher Decision Engine" -[#red]> "Strategy": select appropriate\noptimization strategy
-loop while enough data to build cluster data model
-  "Watcher Decision Engine" -> "Nova API" : get resource state (host, instance, ...)
-  "Watcher Decision Engine" <-- "Nova API" : resource state
-end
-"Watcher Decision Engine" -[#red]> "Watcher Decision Engine": build cluster_data_model
-"Watcher Decision Engine" -> "Strategy" : execute(cluster_data_model)
+"Decision Engine" -> "Strategy" : execute()
+activate "Strategy"
+create "Cluster Data Model Collector"
+"Strategy" -> "Cluster Data Model Collector" : get cluster data model
+
+activate "Cluster Data Model Collector"
+    loop while enough data to build cluster data model
+      "Cluster Data Model Collector" -> "Nova API" : get resource state (\
+host, instance, ...)
+      "Cluster Data Model Collector" <-- "Nova API" : resource state
+    end
+"Cluster Data Model Collector" -> "Strategy" : cluster data model
+deactivate "Cluster Data Model Collector"
+
 loop while enough history data for the strategy
-"Strategy" -> "Ceilometer API": get_aggregated_metrics\n(resource_id,meter_name,period,aggregate_method)
-"Strategy" <-- "Ceilometer API": aggregated metrics
+    "Strategy" -> "Ceilometer API": get necessary metrics
+    "Strategy" <-- "Ceilometer API": aggregated metrics
 end
-"Strategy" -> "Strategy" : compute solution to achieve goal
-"Watcher Decision Engine" <-- "Strategy" : solution = array of actions (i.e. not scheduled yet)
-create "Watcher Planner"
-"Watcher Decision Engine" -[#red]> "Watcher Planner": select appropriate actions scheduler (i.e. Planner implementation)
-"Watcher Decision Engine" -> "Watcher Planner": schedule(audit_id, solution)
-"Watcher Planner" -> "Watcher Planner": schedule actions according to\nscheduling rules/policies
-"Watcher Decision Engine" <-- "Watcher Planner": new action_plan
-"Watcher Decision Engine" -> "Watcher Database" : save new action_plan in database
-"Watcher Decision Engine" -> "Watcher Database" : update audit.state = SUCCEEDED
-"AMQP Bus" <[#blue]- "Watcher Decision Engine" : notify new audit state = SUCCEEDED
+"Strategy" -> "Strategy" : compute/set needed actions for the solution \
+so it achieves its goal
+"Strategy" -> "Strategy" : compute/set efficacy indicators for the solution
+"Strategy" -> "Strategy" : compute/set the solution global efficacy
+"Decision Engine" <-- "Strategy" : solution (contains a list of unordered \
+actions alongside its efficacy indicators as well as its global efficacy)
+deactivate "Strategy"
+
+"Decision Engine" --> "Planner": load actions scheduler (i.e. Planner plugin)
+create "Planner"
+"Decision Engine" -> "Planner": schedule()
+"Planner" -> "Planner": schedule actions according to \
+scheduling rules/policies
+"Decision Engine" <-- "Planner": new action plan
+"Decision Engine" -> "Database" : save new action plan in database
+"Decision Engine" -> "Database" : update audit.state = SUCCEEDED
+"AMQP Bus" <[#blue]- "Decision Engine" : notify new audit state = SUCCEEDED
+
+deactivate "Decision Engine"
 
 @enduml

doc/source/image_src/plantuml/watcher_class_diagram.txt

@@ -1,87 +0,0 @@
-@startuml
-
-abstract class Base {
-    // Timestamp mixin
-    DateTime created_at
-    DateTime updated_at
-
-    // Soft Delete mixin
-    DateTime deleted_at
-    Integer deleted // default = 0
-}
-
-class Strategy {
-    **Integer id** // primary_key
-    String uuid // length = 36
-    String name // length = 63, nullable = false
-    String display_name // length = 63, nullable = false
-    <i>Integer goal_id</i> // ForeignKey('goals.id'), nullable = false
-}
-
-
-class Goal {
-    **Integer id** // primary_key
-    String uuid // length = 36
-    String name // length = 63, nullable = false
-    String display_name // length = 63, nullable=False
-}
-
-
-class AuditTemplate {
-    **Integer id** // primary_key
-    String uuid // length = 36
-    String name // length = 63, nullable = true
-    String description // length = 255, nullable = true
-    Integer host_aggregate // nullable = true
-    <i>Integer goal_id</i> // ForeignKey('goals.id'), nullable = false
-    <i>Integer strategy_id</i> // ForeignKey('strategies.id'), nullable = true
-    JsonString extra
-    String version // length = 15, nullable = true
-}
-
-
-class Audit {
-    **Integer id** // primary_key
-    String uuid // length = 36
-    String type // length = 20
-    String state // length = 20, nullable = true
-    DateTime deadline // nullable = true
-    <i>Integer audit_template_id</i> // ForeignKey('audit_templates.id') \
-nullable = false
-}
-
-
-class Action {
-    **Integer id** // primary_key
-    String uuid // length = 36, nullable = false
-    <i>Integer action_plan_id</i> // ForeignKey('action_plans.id'), nullable = false
-    String action_type // length = 255, nullable = false
-    JsonString input_parameters // nullable = true
-    String state // length = 20, nullable = true
-    String next // length = 36, nullable = true
-}
-
-
-class ActionPlan {
-    **Integer id** // primary_key
-    String uuid // length = 36
-    Integer first_action_id //
-    <i>Integer audit_id</i> // ForeignKey('audits.id'), nullable = true
-    String state // length = 20, nullable = true
-}
-
-"Base" <|-- "Strategy"
-"Base" <|-- "Goal"
-"Base" <|-- "AuditTemplate"
-"Base" <|-- "Audit"
-"Base" <|-- "Action"
-"Base" <|-- "ActionPlan"
-
- "Goal" <.. "Strategy" : Foreign Key
- "Goal" <.. "AuditTemplate" : Foreign Key
- "Strategy" <.. "AuditTemplate" : Foreign Key
- "AuditTemplate" <.. "Audit" : Foreign Key
- "ActionPlan" <.. "Action" : Foreign Key
- "Audit" <.. "ActionPlan" : Foreign Key
-
-@enduml

doc/source/image_src/plantuml/watcher_db_schema_diagram.txt

@@ -0,0 +1,122 @@
+@startuml
+!define table(x) class x << (T,#FFAAAA) >>
+!define primary_key(x) <u>x</u>
+!define foreign_key(x) <i><u>x</u></i>
+hide methods
+hide stereotypes
+
+table(goal) {
+    primary_key(id: Integer)
+    uuid : String[36]
+    name : String[63]
+    display_name : String[63]
+    
+    created_at : DateTime
+    updated_at : DateTime
+    deleted_at : DateTime
+    deleted : Integer
+}
+
+
+table(strategy) {
+    primary_key(id: Integer)
+    foreign_key(goal_id : Integer)
+    uuid : String[36]
+    name : String[63]
+    display_name : String[63]
+    
+    created_at : DateTime
+    updated_at : DateTime
+    deleted_at : DateTime
+    deleted : Integer
+}
+
+
+table(audit_template) {
+    primary_key(id: Integer)
+    foreign_key("goal_id : Integer")
+    foreign_key("strategy_id : Integer, nullable")
+    uuid : String[36]
+    name : String[63], nullable
+    description : String[255], nullable
+    host_aggregate : Integer, nullable
+    extra : JSONEncodedDict
+    version : String[15], nullable
+    
+    created_at : DateTime
+    updated_at : DateTime
+    deleted_at : DateTime
+    deleted : Integer
+}
+
+
+table(audit) {
+    primary_key(id: Integer)
+    foreign_key("audit_template_id : Integer")
+    uuid : String[36]
+    type : String[20]
+    state : String[20], nullable
+    deadline  :DateTime, nullable
+    
+    created_at : DateTime
+    updated_at : DateTime
+    deleted_at : DateTime
+    deleted : Integer
+}
+
+
+table(action_plan) {
+    primary_key(id: Integer)
+    foreign_key("audit_id : Integer, nullable")
+    uuid : String[36]
+    first_action_id : Integer
+    state : String[20], nullable
+    global_efficacy : JSONEncodedDict, nullable
+    
+    created_at : DateTime
+    updated_at : DateTime
+    deleted_at : DateTime
+    deleted : Integer
+}
+
+
+table(action) {
+    primary_key(id: Integer)
+    foreign_key("action_plan_id : Integer")
+    uuid : String[36]
+    action_type : String[255]
+    input_parameters : JSONEncodedDict, nullable
+    state : String[20], nullable
+    next : String[36], nullable
+    
+    created_at : DateTime
+    updated_at : DateTime
+    deleted_at : DateTime
+    deleted : Integer
+}
+
+
+table(efficacy_indicator) {
+    primary_key(id: Integer)
+    foreign_key("action_plan_id : Integer")
+    uuid : String[36]
+    name : String[63]
+    description : String[255], nullable
+    unit : String[63], nullable
+    value : Numeric
+
+    created_at : DateTime
+    updated_at : DateTime
+    deleted_at : DateTime
+    deleted : Integer
+}
+
+ "goal" <.. "strategy" : Foreign Key
+ "goal" <.. "audit_template" : Foreign Key
+ "strategy" <.. "audit_template" : Foreign Key
+ "audit_template" <.. "audit" : Foreign Key
+ "action_plan" <.. "action" : Foreign Key
+ "action_plan" <.. "efficacy_indicator" : Foreign Key
+ "audit" <.. "action_plan" : Foreign Key
+
+@enduml