allow modules to set custom stats (#18946)

can be per run or per host, also aggregate or not
set_stats action plugin as reference implementation
added doc stub
display stats in calblack
made custom stats showing configurable

lib/ansible/executor/stats.py

@@ -19,6 +19,8 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
+from ansible.utils.vars import merge_hash
+
 class AggregateStats:
     ''' holds stats about per-host activity during playbook runs '''
 
@@ -31,6 +33,9 @@ class AggregateStats:
         self.changed   = {}
         self.skipped   = {}
 
+        # user defined stats, which can be per host or global
+        self.custom = {}
+
     def increment(self, what, host):
         ''' helper function to bump a statistic '''
 
@@ -49,3 +54,31 @@ class AggregateStats:
             skipped     = self.skipped.get(host, 0)
         )
 
+    def set_custom_stats(self, which, what, host=None):
+        ''' allow setting of a custom stat'''
+
+        if host is None:
+            host = '_run'
+        if host not in  self.custom:
+            self.custom[host] = {which: what}
+        else:
+            self.custom[host][which] = what
+
+    def update_custom_stats(self, which, what, host=None):
+        ''' allow aggregation of a custom stat'''
+
+        if host is None:
+            host = '_run'
+        if host not in self.custom or which not in self.custom[host]:
+            return self.set_custom_stats(which, what, host)
+
+        # mismatching types
+        if type(what) != type(self.custom[host][which]):
+            return None
+
+        if isinstance(what, dict):
+            self.custom[host][which] =  merge_hash(self.custom[host][which], what)
+        else:
+            # let overloaded + take care of other types
+            self.custom[host][which] += what
+