summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorLamont Granquist <lamont@scriptkiddie.org>2021-01-29 16:15:48 -0800
committerLamont Granquist <lamont@scriptkiddie.org>2021-01-29 16:15:48 -0800
commit5e67fe2c344c4aa19c4533d336289e62749d379d (patch)
tree8acd610c868e15863e97ffb5785ed24fe59d9f17 /docs
parent9defd339d60615fa5555f412581bd97e5bc3a070 (diff)
downloadchef-5e67fe2c344c4aa19c4533d336289e62749d379d.tar.gz
Update the action collection docs with an example
Signed-off-by: Lamont Granquist <lamont@scriptkiddie.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/design_documents/action_collection.md33
1 files changed, 33 insertions, 0 deletions
diff --git a/docs/dev/design_documents/action_collection.md b/docs/dev/design_documents/action_collection.md
index df7dd46a84..367f160fcc 100644
--- a/docs/dev/design_documents/action_collection.md
+++ b/docs/dev/design_documents/action_collection.md
@@ -77,6 +77,39 @@ As the Action Collection API was initially designed around the Resource Reporter
and could easily lift some of the searching features on the name of the resource from the resource collection, and could use a more fluent API
for composing searches.
+# Simple Example
+
+A simple example which can be put into any cookbook's libraries directory and will dump out a list of all the updated (or failed) resources at the end
+of the run is the following:
+
+```
+Chef.run_context.action_collection.register(self)
+
+Chef.event_handler do
+ on :run_completed do
+ MyModule.dump_resources
+ end
+ on :run_failed do
+ MyModule.dump_resources
+ end
+end
+
+class MyModule
+ def self.dump_resources
+ Chef.run_context.action_collection.filtered_collection(up_to_date: false, skipped: false, unprocessed: false).each do |action_record|
+ puts action_record.new_resource
+ end
+ end
+end
+```
+
+For more complicated examples see the `Chef::ResourceReporter` and `Chef::DataCollector` in the source code.
+
+Note that any cookbook library event handlers obviously cannot handle failures that happen earlier in the chef-client run than cookbook library loading
+time. For more truly robust reporting it is best to use the `Chef::DataCollector` directly. A custom implementation would look like copying the defensive
+coding in the data collector into a class which was loaded very early, perhaps at `Chef::Config` loading time (catching errors caused by `Chef::Config` loading
+though is fairly impossible the way the core of the chef-client works though so it is better to keep that simple).
+
# Implementation Details
## Resource Event Lifecycle Hooks