docs for service state
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/6a8af41e Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/6a8af41e Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/6a8af41e Branch: refs/heads/master Commit: 6a8af41e70ab96e361fb58953c2c3f072ff12678 Parents: 099a549 Author: Alex Heneveld <[email protected]> Authored: Tue Aug 26 08:46:48 2014 -0500 Committer: Alex Heneveld <[email protected]> Committed: Wed Aug 27 02:38:15 2014 -0400 ---------------------------------------------------------------------- .../entity/basic/AbstractGroupImpl.java | 1 + .../defining-applications/service-state.md | 73 ++++++++++++++++++++ docs/use/guide/defining-applications/toc.json | 2 + 3 files changed, 76 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/6a8af41e/core/src/main/java/brooklyn/entity/basic/AbstractGroupImpl.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/brooklyn/entity/basic/AbstractGroupImpl.java b/core/src/main/java/brooklyn/entity/basic/AbstractGroupImpl.java index e3520f6..a8ace7f 100644 --- a/core/src/main/java/brooklyn/entity/basic/AbstractGroupImpl.java +++ b/core/src/main/java/brooklyn/entity/basic/AbstractGroupImpl.java @@ -93,6 +93,7 @@ public abstract class AbstractGroupImpl extends AbstractEntity implements Abstra protected void initEnrichers() { super.initEnrichers(); + // check states and upness separately so they can be individually replaced if desired // problem if any children or members are on fire ServiceStateLogic.newEnricherFromChildrenState().checkChildrenAndMembers().requireRunningChildren(getConfig(RUNNING_QUORUM_CHECK)).addTo(this); // defaults to requiring at least one member or child who is up http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/6a8af41e/docs/use/guide/defining-applications/service-state.md ---------------------------------------------------------------------- diff --git a/docs/use/guide/defining-applications/service-state.md b/docs/use/guide/defining-applications/service-state.md new file mode 100644 index 0000000..b142fb1 --- /dev/null +++ b/docs/use/guide/defining-applications/service-state.md @@ -0,0 +1,73 @@ +--- +title: Service State +layout: page +toc: ../guide_toc.json +categories: [use, guide, defining-applications] +--- + +Any entity can use the standard "service-up" and "service-state" +sensors to inform other entities and the GUI about its status. + +In normal operation, entities should publish at least one "service not-up indicator", +using the `ServiceNotUpLogic.updateNotUpIndicator` method. Each such indicator should have +a unique name or input sensor. `Attributes.SERVICE_UP` will then be updated automatically +when there are no not-up indicators. + +When there are transient problems that can be detected, to trigger `ON_FIRE` status +entity code can similarly set `ServiceProblemsLogic.updateProblemsIndicator` with a unique namespace, +and subsequently clear it when the problem goes away. +These problems are reflected at runtime in the `SERVICE_PROBLEMS` sensor, +allowing multiple problems to be tracked independently. + +When an entity is changing the expected state, e.g. starting or stopping, +the expected state can be set using `ServiceStateLogic.setExpectedState`; +this expected lifecycle state is considered together with `SERVICE_UP` and `SERVICE_PROBLEMS` +to compute the actual state. By default the logic in `ComputeServiceState` is applied. + +For common entities, good out-of-the-box logic is applied, as follows: + +* For `SoftwareProcess` entities, lifecycle service state is updated by the framework + and a service not-up indicator is linked to the driver `isRunning()` check. + +* For common parents, including `AbstractApplication` and `AbstractGroup` subclasses (including clusters, fabrics, etc), + the default enrichers analyse children and members to set a not-up indicator + (requiring at least one child or member who is up) and a problem indicator + (if any children or members are on-fire). + In some cases other quorum checks are preferable; this can be set e.g. by overriding + the `UP_QUORUM_CHECK` or the `RUNNING_QUORUM_CHECK`, as follows: + + public static final ConfigKey<QuorumCheck> UP_QUORUM_CHECK = ConfigKeys.newConfigKeyWithDefault(AbstractGroup.UP_QUORUM_CHECK, + "Require all children and members to be up for this node to be up", + QuorumChecks.all()); + + Alternatively the `initEnrichers()` method can be overridden to specify a custom-configured + enricher or set custom config key values (as done e.g. in `DynamicClusterImpl` so that + zero children is permitted provided when the initial size is configured to be 0). + + +For sample code to set and more information on these methods' behaviours, +see javadoc in `ServiceStateLogic`, +overrides of `AbstractEntity.initEnrichers()` +and tests in `ServiceStateLogicTests`. + +<!-- TODO include more documentation, sample code (ideally extracted on the fly from test cases so we know it works!) --> + + +## Notes on Advanced Use + +The enricher to derive `SERVICE_UP` and `SERVICE_STATE_ACTUAL` from the maps and expected state values discussed above +is added by the `AbstractEntity.initEnrichers()` method. +This method can be overridden -- or excluded altogether by by overriding `init()` -- +and can add enrichers created using the `ServiceStateLogic.newEnricherFromChildren()` method +suitably customized using methods on the returned spec object, for instance to look only at members +or specify a quorum function (from `QuorumChecks`). +If different logic is required for computing `SERVICE_UP` and `SERVICE_STATE_ACTUAL`, +use `ServiceStateLogic.newEnricherFromChildrenState()` and `ServiceStateLogic.newEnricherFromChildrenUp()`, +noting that the first of these will replace the enricher added by the default `initEnrichers()`, +whereas the second one runs with a different namespace (unique tag). +For more information consult the javadoc on those classes. + +Entities can set `SERVICE_UP` and `SERVICE_STATE_ACTUAL` directly. +Provided these entities never use the `SERVICE_NOT_UP_INDICATORS` and `SERVICE_PROBLEMS` map, +the default enrichers will not override these values. + http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/6a8af41e/docs/use/guide/defining-applications/toc.json ---------------------------------------------------------------------- diff --git a/docs/use/guide/defining-applications/toc.json b/docs/use/guide/defining-applications/toc.json index c8b32aa..08940a8 100644 --- a/docs/use/guide/defining-applications/toc.json +++ b/docs/use/guide/defining-applications/toc.json @@ -12,6 +12,8 @@ "file": "{{ site.url }}/use/guide/defining-applications/deploying-yaml.html" }, { "title": "YAML Reference", "file": "{{ site.url }}/use/guide/defining-applications/yaml-reference.html" }, +{ "title": "Service State", + "file": "{{ site.url }}/use/guide/defining-applications/service-state.html" }, { "title": "Maven Archetype", "file": "{{ site.url }}/use/guide/defining-applications/archetype.html" } ]
