doc: add building of instrument method map

doc/source/conf.py

@@ -33,6 +33,7 @@ from build_plugin_docs import (generate_plugin_documentation,
                                generate_run_config_documentation,
                                generate_meta_config_documentation,
                                generate_target_documentation)
+from build_instrument_method_map import generate_instrument_method_map
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -322,6 +323,7 @@ def setup(app):
     generate_target_documentation('plugins')
     generate_run_config_documentation('run_config')
     generate_meta_config_documentation('run_config')
+    generate_instrument_method_map(os.path.join('developer_reference', 'instrument_method_map.rst'))
     app.add_object_type('confval', 'confval',
                         objname='configuration value',
                         indextemplate='pair: %s; configuration value')

doc/source/developer_reference/writing_extensions.rst

@@ -714,10 +714,11 @@ hooked up to the supported signals. Once a signal is broadcasted, the
 corresponding registered method is invoked.
 
 Each method in Instrument must take two arguments, which are self and context.
-Supported signals can be found in the :ref:`Signals Documentation
-<instruments_method_map>` To make implementations easier and common, the basic
-steps to add new instrument is similar to the steps to add new workload and an
-example can be found :ref:`here <adding-an-instrument-example>`.
+Supported method and their corresponding signals can be found in the
+:ref:`Signals Documentation <instruments_method_map>` To make implementations
+easier and common, the basic steps to add new instrument is similar to the steps
+to add new workload and an example can be found
+:ref:`here <adding-an-instrument-example>`.
 
 .. _instrument-api:
 
@@ -871,6 +872,9 @@ Below is a simple instrument that measures the execution time of a workload::
             execution_time = self.end_time - self.start_time
             context.add_metric('execution_time', execution_time, 'seconds')
 
+
+.. include:: developer_reference/instrument_method_map.rst
+
 .. _adding-an-output-processor:
 
 Adding an Output processor

doc/source/instrument_method_map.template

@@ -0,0 +1,17 @@
+.. _instruments_method_map:
+
+Instrumentation Signal-Method Mapping
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Instrument methods get automatically hooked up to signals based on their names. Mostly, the method
+name correponds to the name of the signal, however there are a few convienience aliases defined
+(listed first) to make  easier to relate instrumenation code to the workload execution model.
+
+$signal_names
+
+The methods above may be decorated with on the listed decorators to  set the priority of the
+Instrument method realive to other callbacks registered for the signal (within the same priority
+level, callbacks are invoked in the order they were registered). The table below shows the mapping
+of the decorator to the corresponding priority:
+
+$priority_prefixes