Repository: incubator-apex-core Updated Branches: refs/heads/master a703921e8 -> 39e9beeeb
Documentation for Affinity Rules Project: http://git-wip-us.apache.org/repos/asf/incubator-apex-core/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-apex-core/commit/ffb05175 Tree: http://git-wip-us.apache.org/repos/asf/incubator-apex-core/tree/ffb05175 Diff: http://git-wip-us.apache.org/repos/asf/incubator-apex-core/diff/ffb05175 Branch: refs/heads/master Commit: ffb051757933630667aa95e80b6b0ccc6c5a776f Parents: c2903da Author: ishark <icarkat...@gmail.com> Authored: Tue May 3 23:50:21 2016 -0700 Committer: ishark <icarkat...@gmail.com> Committed: Tue May 3 23:56:12 2016 -0700 ---------------------------------------------------------------------- docs/application_development.md | 78 ++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-apex-core/blob/ffb05175/docs/application_development.md ---------------------------------------------------------------------- diff --git a/docs/application_development.md b/docs/application_development.md index 8f98eba..07a54e1 100644 --- a/docs/application_development.md +++ b/docs/application_development.md @@ -1732,6 +1732,84 @@ the network card. THREAD_LOCAL and CONTAINER_LOCAL streams do not use a buffer server as this stream is in a single process. The other two do. +Affinity Rules +------------------ +Affinity Rules in Apex provide a way to specify hints on how operators should be deployed in a cluster. Sometimes you may want to allocate certain operators on the same or different nodes for performance or other reasons. Affinity rules can be used in such cases to make sure these considerations are honored by platform. + +There can be two types of rules: Affinity and Anti-affinity rules. Affinity rule indicates that group of operators in the rule should be allocated together. On the other hand, anti-affinity rule indicates that the group of operators should be allocated separately. + +### Specifying Affinity Rules +A list of Affinity Rules can be specified for an application by setting attribute: DAGContext.AFFINITY_RULES_SET. +Here is code snippet for setting Affinity rules for an application in populateDag method: +```java +AffinityRulesSet ruleSet = new AffinityRulesSet(); +List<AffinityRule> rules = new ArrayList<>(); +// Add Affinity rules as per requirement +rules.add(new AffinityRule(Type.ANTI_AFFINITY, Locality.NODE_LOCAL, false, "rand", "operator1", "operator2")); +rules.add(new AffinityRule(Type.AFFINITY, Locality.CONTAINER_LOCAL, false, "console", "rand")); +ruleSet.setAffinityRules(rules); +dag.setAttribute(DAGContext.AFFINITY_RULES_SET, ruleSet); +``` + +As shown in the example above, each rule has a type Affinity or Anti_Affinity indicating whether operators in group should be allocated together or separate. These can be applied on any operators in DAG. + +The operators for rule can be provided either as a list of 2 or more operator names or as a regular expression. The regex should match at least two operators in DAG to be considered a valid rule. Here is example of rule with regex to allocate all the operators in DAG on the same node: +```java +// Allocate all operators starting with console on same container +rules.add(new AffinityRule(Type.AFFINITY, "*" , Locality.NODE_LOCAL, false)); +``` +Likewise, operators for rule can also be added as a list: +```java +// Rule for Operators rand, operator1 and operator2 should not be allocated on same node +rules.add(new AffinityRule(Type.ANTI_AFFINITY, Locality.NODE_LOCAL, false, "rand", "operator1", "operator2")); +``` +To indicate affinity or anti-affinity between partitions of a single operator, list should contain the same operator name twice, as shown in the example below for 'TestOperator'. This will ensure that platform will allocate physical partitions of this operator on different nodes. +```java +// Rule for Partitions of TestOperator should not be allocated on the same node +rules.add(new AffinityRule(Type.ANTI_AFFINITY, Locality.NODE_LOCAL, false, "TestOperator", "TestOperator")); +``` +Another important parameter to indicate affinity rule is the Locality constraint. Similar to Stream locality, the affinity rule will be applied at either THREAD_LOCAL, CONTAINER_LOCAL or NODE_LOCAL level. Support for RACK_LOCAL is not added yet. + +The last configurable parameter for Affinity Rules is strict or preferred rule. A true value for this parameter indicates that the rule should be relaxed in case sufficient resources are not available. + +### Specifying affinity rules from properties +The same set of rules can also be added from properties.xml by setting value for attribute DAGContext.AFFINITY_RULES_SET as JSON string. For example: +```xml +<property> + <name>dt.application.AffinityRulesSampleApplication.attr.AFFINITY_RULES_SET</name> + <value> + { + "affinityRules": [ + { + "operatorRegex": "console*", + "locality": "CONTAINER_LOCAL", + "type": "AFFINITY", + "relaxLocality": false + }, + { + "operatorsList": [ + "rand", + "passThru" + ], + "locality": "NODE_LOCAL", + "type": "ANTI_AFFINITY", + "relaxLocality": false + }, + { + "operatorsList": [ + "passThru", + "passThru" + ], + "locality": "NODE_LOCAL", + "type": "ANTI_AFFINITY", + "relaxLocality": false + } + ] + } +</property> +``` +Affinity rules which conflict with Stream locality or Host preference are validated during DAG validation phase. + Validating an Application --------------------------------------
