Github user drigodwin commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/160#discussion_r109780899
--- Diff: guide/java/policies.md ---
@@ -121,151 +120,79 @@ The ConditionalSuspendPolicy will suspend and resume
a target policy based on co
The LoadBalancingPolicy is attached to a pool of "containers", each of
which can host one or more migratable "items". The policy monitors the
workrates of the items and effects migrations in an attempt to ensure that the
containers are all sufficiently utilized without any of them being overloaded.
-### Enrichers
-
-#### Transformer
-
-- org.apache.brooklyn.enricher.stock.Transformer
-
-Transforms attributes of an entity.
-
-{% highlight yaml %}
-brooklyn.enrichers:
-- type: org.apache.brooklyn.enricher.stock.Transformer
- brooklyn.config:
- enricher.sourceSensor: $brooklyn:sensor("urls.tcp.string")
- enricher.targetSensor: $brooklyn:sensor("urls.tcp.withBrackets")
- enricher.targetValue: $brooklyn:formatString("[%s]",
$brooklyn:attributeWhenReady("urls.tcp.string"))
-{% endhighlight %}
-
-#### Propagator
-
-- org.apache.brooklyn.enricher.stock.Propagator
-
-Use propagator to duplicate one sensor as another, giving the supplied
sensor mapping.
-The other use of Propagator is where you specify a producer (using
`$brooklyn:entity(...)` as below)
-from which to take sensors; in that mode you can specify `propagate` as a
list of sensors whose names are unchanged,
-instead of (or in addition to) this map
-{% highlight yaml %}
-brooklyn.enrichers:
-- type: org.apache.brooklyn.enricher.stock.Propagator
- brooklyn.config:
- producer: $brooklyn:entity("cluster")
-- type: org.apache.brooklyn.enricher.stock.Propagator
- brooklyn.config:
- sensorMapping:
- $brooklyn:sensor("url"):
$brooklyn:sensor("org.apache.brooklyn.core.entity.Attributes", "main.uri")
-{% endhighlight %}
-
-#### Custom Aggregating
-
-- org.apache.brooklyn.enricher.stock.Aggregator
-
-Aggregates multiple sensor values (usually across a tier, esp. a cluster)
and performs a supplied aggregation method to them to return an aggregate
figure, e.g. sum, mean, median, etc.
-
-{% highlight yaml %}
-brooklyn.enrichers:
-- type: org.apache.brooklyn.enricher.stock.Aggregator
- brooklyn.config:
- enricher.sourceSensor: $brooklyn:sensor("webapp.reqs.perSec.windowed")
- enricher.targetSensor: $brooklyn:sensor("webapp.reqs.perSec.perNode")
- enricher.aggregating.fromMembers: true
- transformation: average
-{% endhighlight %}
+Writing a Policy
+----------------
-#### Joiner
+### Your First Policy
-- org.apache.brooklyn.enricher.stock.Joiner
-
-Joins a sensor whose output is a list into a single item joined by a
separator.
-
-{% highlight yaml %}
-brooklyn.enrichers:
-- type: org.apache.brooklyn.enricher.stock.Joiner
- brooklyn.config:
- enricher.sourceSensor: $brooklyn:sensor("urls.tcp.list")
- enricher.targetSensor: $brooklyn:sensor("urls.tcp.string")
- uniqueTag: urls.quoted.string
+Policies perform the active management enabled by Brooklyn.
+Each policy instance is associated with an entity,
+and at runtime it will typically subscribe to sensors on that entity or
children,
+performing some computation and optionally actions when a subscribed
sensor event occurs.
+This action might be invoking an effector or emitting a new sensor,
+depending the desired behavior is.
+
+Writing a policy is straightforward.
+Simply extend ``AbstractPolicy``,
+overriding the ``setEntity`` method to supply any subscriptions desired:
+
+{% highlight java %}
+ @Override
+ public void setEntity(EntityLocal entity) {
+ super.setEntity(entity)
+ subscribe(entity, TARGET_SENSOR, this)
+ }
{% endhighlight %}
-#### Delta Enricher
-
-- org.apache.brooklyn.policy.enricher.Delta Enricher
+and supply the computation and/or activity desired whenever that event
occurs:
-Converts absolute sensor values into a delta.
-
-#### Time-weighted Delta
-
-- org.apache.brooklyn.enricher.stock.YamlTimeWeightedDeltaEnricher
-
-Converts absolute sensor values into a delta/second.
-
-{% highlight yaml %}
-brooklyn.enrichers:
-- type: org.apache.brooklyn.enricher.stock.YamlTimeWeightedDeltaEnricher
- brooklyn.config:
- enricher.sourceSensor: reqs.count
- enricher.targetSensor: reqs.per_sec
- enricher.delta.period: 1s
+{% highlight java %}
+ @Override
+ public void onEvent(SensorEvent<Integer> event) {
+ int val = event.getValue()
+ if (val % 2 == 1)
+ entity.sayYoureOdd();
+ }
{% endhighlight %}
-#### Rolling Mean
-
-- org.apache.brooklyn.policy.enricher.RollingMeanEnricher
-
-Converts the last *N* sensor values into a mean.
-
-#### Rolling Time-window Mean
-
-- org.apache.brooklyn.policy.enricher.RollingTimeWindowMeanEnricher
-Converts the last *N* seconds of sensor values into a weighted mean.
+You'll want to do more complicated things, no doubt,
+like access other entities, perform multiple subscriptions,
+and emit other sensors -- and you can.
+See the best practices below and source code for some commonly used
policies and enrichers,
+such as ``AutoScalerPolicy`` and ``RollingMeanEnricher``.
-#### Http Latency Detector
+One rule of thumb, to close on:
+try to keep policies simple, and compose them together at runtime;
+for instance, if a complex computation triggers an action,
+define one **enricher** policy to aggregate other sensors and emit a new
sensor,
+then write a second policy to perform that action.
--
org.apache.brooklyn.policy.enricher.RollingTimeWindowMeanEnricher.HttpLatencyDetector
-An Enricher which computes latency in accessing a URL.
+### Best Practice
-#### Combiner
+The following recommendations should be considered when designing policies:
-- org.apache.brooklyn.enricher.stock.Combiner
+#### Management should take place as "low" as possible in the hierarchy
+* place management responsibility in policies at the entity, as much as
possible ideally management should take run as a policy on the relevant entity
-Can be used to combine the values of sensors. This enricher should be
instantiated using Enrichers.buider.combining(..).
-This enricher is only available in Java blueprints and cannot be used in
YAML.
+* place escalated management responsibility at the parent entity. Where
this is impractical, perhaps because two aspects of an entity are best handled
in two different places, ensure that the separation of responsibilities is
documented and there is a group membership relationship between
secondary/aspect managers.
-#### Note On Enricher Producers
-If an entity needs an enricher whose source sensor
(`enricher.sourceSensor`) belongs to another entity, then the enricher
-configuration must include an `enricher.producer` key referring to the
other entity.
+#### Policies should be small and composable
-For example, if we consider the Transfomer from above, suppose that
`enricher.sourceSensor: $brooklyn:sensor("urls.tcp.list")`
-is actually a sensor on a different entity called `load.balancer`. In this
case, we would need to supply an
-`enricher.producer` value.
+e.g. one policy which takes a sensor and emits a different, enriched
sensor, and a second policy which responds to the enriched sensor of the first
(e.g. a policy detects a process is maxed out and emits a TOO_HOT sensor; a
second policy responds to this by scaling up the VM where it is running,
requesting more CPU)
-{% highlight yaml %}
-brooklyn.enrichers:
-- type: org.apache.brooklyn.enricher.stock.Transformer
- brooklyn.config:
- enricher.producer: $brooklyn:entity("load.balancer")
- enricher.sourceSensor: $brooklyn:sensor("urls.tcp.string")
- enricher.targetSensor: $brooklyn:sensor("urls.tcp.withBrackets")
- enricher.targetValue: |
- $brooklyn:formatString("[%s]",
$brooklyn:attributeWhenReady("urls.tcp.string"))
-{% endhighlight %}
+#### Where a policy cannot resolve a situation at an entity, the issue
should be escalated to a manager with a compatible policy.
-It is important to note that the value supplied to `enricher.producer`
must be immediately resolvable. While it would be valid
-DSL syntax to write:
+Typically escalation will go to the entity parent, and then cascade up.
+e.g. if the earlier VM CPU cannot be increased, the TOO_HOT event may go
to the parent, a cluster entity, which attempts to balance. If the cluster
cannot balance, then to another policy which attempts to scale out the cluster,
and should the cluster be unable to scale, to a third policy which emits
TOO_HOT for the cluster.
-{% highlight yaml %}
-enricher.producer:
brooklyn:entity($brooklyn:attributeWhenReady("load.balancer.entity"))
-{% endhighlight %}
+#### Management escalation should be carefully designed so that policies
are not incompatible
-(assuming the `load.balancer.entity` sensor returns a Brooklyn entity),
this will not function properly because `enricher.producer`
-will unsuccessfully attempt to get the supplied entity immediately.
+Order policies carefully, and mark sensors as "handled" (or potentially
"swallow" them locally), so that subsequent policies and parent entities do not
take superfluous (or contradictory) corrective action.
-Next: Writing a Policy
----------------------------
+### Implementation Classes
-To write a policy, see the section on [Writing a Policy]({{
site.path.guide }}/java/policy.html).
+- extend ``AbstractPolicy``, or override an existing policy
--- End diff --
Perhaps link to the javadoc or code
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
