This is an automated email from the ASF dual-hosted git repository.
heneveld pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 5245aa5c document new soft retention and on_update_child bits
new 5701d52e Merge branch 'master' of github.com:apache/brooklyn-docs
5245aa5c is described below
commit 5245aa5c3ed0d062813dd039b7425afbe672eb63
Author: Alex Heneveld <[email protected]>
AuthorDate: Mon Apr 1 17:00:32 2024 +0100
document new soft retention and on_update_child bits
---
guide/blueprints/workflow/settings.md | 6 +++++-
guide/blueprints/workflow/steps/steps.yaml | 2 ++
2 files changed, 7 insertions(+), 1 deletion(-)
diff --git a/guide/blueprints/workflow/settings.md
b/guide/blueprints/workflow/settings.md
index ab7af87c..c9d409c9 100644
--- a/guide/blueprints/workflow/settings.md
+++ b/guide/blueprints/workflow/settings.md
@@ -359,7 +359,9 @@ and/or as part of a workflow step, if the retention period
should be changed dep
Where not explicitly set, a system-wide retention default is used. This can be
configured in `brooklyn.properties` using
the key `workflow.retention.default`. If no supplied, Brooklyn defaults to
`3`, meaning it will keep the three most
-recent invocations of a workflow, with no time limit, and
+recent invocations of a workflow, with no time limit.
+
+Workflows may be kept in-memory for a longer period than persisted to disk,
depending on the memory available. This allows, for example, `disabled` and `0`
to be indicated to minimize persistence requirements, while maintaining UI and
API access to workflow state "softly", that is to say if memory permits. The
key `workflow.retention.default.soft` can be configured in
`brooklyn.properties` to override the default limit of such workflows kept in
memory, from the default value of `3`, or t [...]
Workflow retention is done on a per-entity basis based by default on a hash of
the workflow name. Typically workflow
definitions for effectors, sensors, and policies all get unique names for that
definition, so the retention applies
@@ -398,6 +400,8 @@ Permitted `<value>` expressions in either case are:
* `max` means completed workflow instances must be retained if they meet any
of the constraints implied by
the `<value>` arguments, i.e. `max(2, 3, 1h, 2h)` means to keep the 3 most
recent instances irrespective of when
they run, and to keep all instances for up to two hours
+* `<value> soft <soft_value>` where `<soft_value>` can be any of the above, to
specify an explicit in-memory soft-retention limit, and `<value>` is any
retention expression indicating the normal on-disk retention (where `<value>`
must not indicate an additional `soft` or `hard` expression)
+* `<value> hard` as per `soft` but indicating that the `<value>` is both the
on-disk and in-memory limit
* `disabled`, to prevent persistence of a workflow, causing less work for the
system where workflows don't need to be
stored; such workflows will not be replayable by an operator or recoverable
on failover;
this should not be used with workflows that acquire a `lock` unless the
entity has special handlers to clear locks
diff --git a/guide/blueprints/workflow/steps/steps.yaml
b/guide/blueprints/workflow/steps/steps.yaml
index 9cb3aae6..f55141b8 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -567,6 +567,8 @@
the default behavior is to invoke an `on_update` effector at the
child (if there is such an effector, otherwise do nothing);
if the name or any policies may need to change on update, that
should be considered in this workflow;
if the `update-children` is performed frequently, it might be
efficient in this method to check whether the `item` has changed
+ * `on_update_child`: as `on_update`, but run in the context of the
`child` entity for easier configuration there,
+ still with access to `item` and `index`
* `on_delete`: a workflow to run on each child which no longer has a
corresponding item prior to its being deleted;
the default behavior is to invoke an `on_delete` effector at the
child (if there is such an effector, or nothing);
