Merge pull request #138 from AndreasGocht/instrumenter_file

Allows the usage of an Instrumenter file, which allows explicit instrument functions without changing any code.

Author: AndreasGocht

README.md

@@ -13,6 +13,7 @@ scorep is a module that allows tracing of python scripts using [Score-P](https:/
   * [Instrumenter](#instrumenter)
     + [Instrumenter Types](#instrumenter-types)
     + [Instrumenter User Interface](#instrumenter-user-interface)
+    + [Instrumenter File](#instrumenter-file)
   * [MPI](#mpi)
   * [User Regions](#user-regions)
   * [Overview about Flags](#overview-about-flags)
@@ -102,6 +103,7 @@ with scorep.instrumenter.enable():
 The main idea is to reduce the instrumentation overhead for regions that are not of interest.
 Whenever the instrumenter is disabled, function enter or exits will not be trace.
 However, user regions as described in [User Regions](#user-regions) are not affected.
+Both functions are also available as decorators.
 
 As an example:
 
@@ -155,6 +157,45 @@ with scorep.instrumenter.disable():
 will only disable the instrumenter, but `my_fun_calls` will not appear in the trace or profile, as the second call to `scorep.instrumenter.disable` did not change the state of the instrumenter.
 Please look to [User Regions](#user-regions), if you want to annotate a region, no matter what the instrumenter state is.
 
+### Instrumenter File
+
+Handing a Python file to `--instrumenter-file` allows the instrumentation of modules and functions without changing their code.
+The file handed to `--instrumenter-file` is executed before the script is executed so that the original function definition can be overwritten before the function is executed.
+However, using this approach, it is no longer possible to track the bring up of the module.
+
+To simplify the instrumentation, the user instrumentation contains two helper calls:
+```
+scorep.user.instrument_function(function, instrumenter_fun=scorep.user.region)
+scorep.user.instrument_module(module, instrumenter_fun=scorep.user.region):
+```
+while `instrumenter_fun` might be one of:
+ * `scorep.user.region`, decorator as explained below
+ * `scorep.instrumenter.enable`, decorator as explained above
+ * `scorep.instrumenter.disable`, decorator as explained above
+
+Using the `scorep.instrumenter` decorators, the instrumentation can be enabled or disabled from the given function.
+The function is executed below `enable` or `disable`.
+Using `scorep.user.region`, it is possible to instrument a full python program.
+However, I discourage this usage, as the overhead of the user instrumentation is higher than the built-in instrumenters.
+
+Using `scorep.user.instrument_module`, all functions of the given Python Module are instrumented.
+
+An example instrumenter file might look like the following:
+```
+import scorep.user
+
+# import module that shall be instrumented
+import module_to_instrument
+import module
+
+# hand over the imported module, containing functions which shall be instrumented
+scorep.user.instrument_module(module_to_instrument)
+
+# hand the function to be instrumented, and overwrite the original definiton of that function
+module.function_to_instrument = scorep.user.instrument_function(module.function_to_instrument)
+
+```
+
 ## MPI
 
 To use trace an MPI parallel application, please specify

scorep/__main__.py

@@ -28,6 +28,7 @@ def scorep_main(argv=None):
         instrumenter_type = "cProfile"
     else:
         instrumenter_type = "profile"
+    instrumenter_file = None
 
     for elem in argv[1:]:
         if parse_scorep_commands:
@@ -52,6 +53,9 @@ def scorep_main(argv=None):
             elif "--instrumenter-type" in elem:
                 param = elem.split("=")
                 instrumenter_type = param[1]
+            elif "--instrumenter-file" in elem:
+                param = elem.split("=")
+                instrumenter_file = param[1]
             elif elem[0] == "-":
                 scorep_config.append(elem)
             else:
@@ -96,6 +100,11 @@ def scorep_main(argv=None):
 
     tracer = scorep.instrumenter.get_instrumenter(not no_instrumenter,
                                                   instrumenter_type)
+
+    if instrumenter_file:
+        with open(instrumenter_file) as f:
+            exec(f.read())
+
     try:
         with open(progname) as fp:
             code = compile(fp.read(), progname, 'exec')

scorep/user.py

@@ -135,6 +135,17 @@ def __exit__(self, exc_type, exc_value, traceback):
         return False
 
 
+def instrument_function(fun, instrumenter_fun=region):
+    return instrumenter_fun()(fun)
+
+
+def instrument_module(module, instrumenter_fun=region):
+    for elem in dir(module):
+        module_fun = module.__dict__[elem]
+        if inspect.isfunction(module_fun):
+            module.__dict__[elem] = instrument_function(module_fun, instrumenter_fun)
+
+
 def rewind_begin(name, file_name=None, line_number=None):
     """
     Begin of a Rewind region. If file_name or line_number is None, both will

test/cases/external_instrumentation.py

@@ -0,0 +1,5 @@
+import scorep.user
+
+import instrumentation2
+
+scorep.user.instrument_module(instrumentation2)

test/test_scorep.py

@@ -254,6 +254,29 @@ def test_user_instrumentation(scorep_env, instrumenter):
     assert re.search('LEAVE[ ]*[0-9 ]*[0-9 ]*Region: "instrumentation2:baz"', std_out)
 
 
+@foreach_instrumenter
+def test_external_user_instrumentation(scorep_env, instrumenter):
+    trace_path = get_trace_path(scorep_env)
+
+    std_out, std_err = call_with_scorep(
+        "cases/instrumentation.py",
+        ["--nocompiler", "--noinstrumenter", "--instrumenter-type=" +
+            instrumenter, "--instrumenter-file=cases/external_instrumentation.py"],
+        env=scorep_env,
+    )
+
+    assert std_err == ""
+    assert std_out == "hello world\nbaz\nbar\n"
+
+    std_out, std_err = call(["otf2-print", trace_path])
+
+    assert std_err == ""
+    assert re.search('ENTER[ ]*[0-9 ]*[0-9 ]*Region: "instrumentation2:bar"', std_out)
+    assert re.search('LEAVE[ ]*[0-9 ]*[0-9 ]*Region: "instrumentation2:bar"', std_out)
+    assert re.search('ENTER[ ]*[0-9 ]*[0-9 ]*Region: "instrumentation2:baz"', std_out)
+    assert re.search('LEAVE[ ]*[0-9 ]*[0-9 ]*Region: "instrumentation2:baz"', std_out)
+
+
 @foreach_instrumenter
 def test_error_region(scorep_env, instrumenter):
     trace_path = get_trace_path(scorep_env)