You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To use trace an MPI parallel application, please specify
61
-
62
-
```
63
-
python -m scorep --mpp=mpi <script.py>
64
-
```
65
-
66
-
## User instrumentation
67
-
### User Regions
68
-
Since version 2.0 the python bindings support context managers for user regions:
69
-
70
-
```
71
-
with scorep.user.region("region_name"):
72
-
do_something()
73
-
```
74
-
75
-
Since version 2.1 the python bindings support also decorators for functions:
76
-
77
-
```
78
-
@scorep.user.region("region_name")
79
-
def do_something():
80
-
#do some things
81
-
```
82
-
If no region name is given, the function name will be used e.g.:
83
-
84
-
```
85
-
@scorep.user.region()
86
-
def do_something():
87
-
#do some things
88
-
```
89
-
90
-
will result in `__main__:do_something`.
61
+
## Instrumenter
62
+
The instrumenter ist the key part of the bindings.
63
+
He registers with the Python tracing interface, and cares about the fowarding of events to Score-P.
64
+
There are currently three different instrumenter types available as described in the following section [Instrumenter Types](#instrumenter-types) .
65
+
A user interface, to dynamically enable and disable the automatic instrumentation, using the python hooks, is also available and described under [Instrumenter User Interface](instrumenter-user-interface)
91
66
92
-
The traditional calls to define a region still exists, but the usage is discouraged:
93
-
94
-
```
95
-
scorep.user.region_begin("region_name")
96
-
scorep.user.region_end("region_name")
97
-
```
98
-
99
-
User parameters can be used in any case:
100
-
101
-
```
102
-
scorep.user.parameter_int(name, val)
103
-
scorep.user.parameter_uint(name, val)
104
-
scorep.user.parameter_string(name, string)
105
-
```
106
-
107
-
where `name` defines the name of the parameter or region, while `val` or `string` represents the value that is passed to Score-P.
108
-
109
-
Disabeling the recording with Score-P is still also possilbe:
110
-
111
-
```
112
-
scorep.user.enable_recording()
113
-
scorep.user.disable_recording()
114
-
```
115
-
116
-
However, please be aware that the runtime impact of disabeling Score-P is rather small, as the instrumenter is still active. For details about the instrumenter, please see [Instrumenter](#Instrumenter).
117
-
118
-
### Instrumenter
67
+
### Instrumenter Types
119
68
With version 2.0 of the python bindings, the term "instrumenter" is introduced. The instrumenter describes the class that maps the Python `trace` or `profile` events to Score-P. Please be aware, that `trace` and `profile` does not refer to the traditional Score-P terms of tracing and profiling, but to the Python functions [sys.settrace](https://docs.python.org/3/library/sys.html#sys.settrace) and [sys.setprofile](https://docs.python.org/3/library/sys.html#sys.setprofile).
120
69
121
70
The instrumenter that shall be used for tracing can be specified using `--instrumenter-type=<type>`.
@@ -124,9 +73,14 @@ Currently there are the following tacers available:
124
73
*`trace` implements `call` and `return`
125
74
*`dummy` does nothing, can be used without `-m scorep` (as done by user instrumentation)
126
75
127
-
The `profile` instrumenter should have a smaller overhead than `trace`.
76
+
The `profile` instrumenter should have a smaller overhead than `trace`.
77
+
78
+
It is possible to disable the instrumenter passing `--noinstrumenter`.
79
+
However, the [Instrumenter User Interface](instrumenter-user-interface) may override this flag.
80
+
81
+
### Instrumenter User Interface
128
82
129
-
Moreover it is possible to disable (and enable) the instrumenter in the sourcecode:
83
+
It is possible to enable or disable the instrumenter during the program runtime using a user interface:
130
84
131
85
```
132
86
with scorep.instrumenter.disable():
@@ -136,10 +90,9 @@ with scorep.instrumenter.enable():
136
90
do_something()
137
91
```
138
92
139
-
or during startup with `--noinstrumenter`. The given function calls override this flag.
140
-
141
93
The main idea is to reduce the instrumentation overhead for regions that are not of interest.
142
94
Whenever the instrumenter is disabled, function enter or exits will not be trace.
95
+
However, user regions as described in [User Regions](#user-regions) are not affected.
143
96
144
97
As an example:
145
98
@@ -164,11 +117,9 @@ with scorep.instrumenter.enable():
164
117
[...]
165
118
```
166
119
and run the code with `python -m scorep --noinstrumenter run.py` only the call to np.dot and everything below will be instrumented.
167
-
Please be aware, that user instrumentation, using scorep.user will always be recorded.
168
-
169
120
170
-
With version 3.1 the bindings support the annotation of regions where the instrumenter was explicit enabled or disabled.
171
-
You can now pass a `region_name` to `scorep.instrumenter.enable("enabled_region_name")`and`scorep.instrumenter.disable("disabled_region_name")`.
121
+
With version 3.1 the bindings support the annotation of regions where the instrumenter setting was changed.
122
+
You can pass a `region_name` to the instrumenter calls, e.g. `scorep.instrumenter.enable("enabled_region_name")`or`scorep.instrumenter.disable("disabled_region_name")`.
172
123
This might be useful if you do something expensive, and just want to know how long it takes, but you do not care what happens exactly e.g.:
173
124
174
125
```
@@ -184,6 +135,76 @@ with scorep.instrumenter.disable("my_fun_calls"):
184
135
185
136
`my_fun_calls` will be present in the trace or profile but `fun_calls` will not.
186
137
138
+
However, doing
139
+
```
140
+
[...]
141
+
with scorep.instrumenter.disable():
142
+
with scorep.instrumenter.disable("my_fun_calls"):
143
+
fun_calls(1000000)
144
+
[...]
145
+
```
146
+
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.
147
+
Please look to [User Regions](#user-regions), if you want to annotate a region, no matter what the instrumenter state is.
148
+
149
+
## MPI
150
+
151
+
To use trace an MPI parallel application, please specify
152
+
153
+
```
154
+
python -m scorep --mpp=mpi <script.py>
155
+
```
156
+
157
+
## User Regions
158
+
Since version 2.0 the python bindings support context managers for user regions:
159
+
160
+
```
161
+
with scorep.user.region("region_name"):
162
+
do_something()
163
+
```
164
+
165
+
Since version 2.1 the python bindings support also decorators for functions:
166
+
167
+
```
168
+
@scorep.user.region("region_name")
169
+
def do_something():
170
+
#do some things
171
+
```
172
+
If no region name is given, the function name will be used e.g.:
173
+
174
+
```
175
+
@scorep.user.region()
176
+
def do_something():
177
+
#do some things
178
+
```
179
+
180
+
will result in `__main__:do_something`.
181
+
182
+
The traditional calls to define a region still exists, but the usage is discouraged:
183
+
184
+
```
185
+
scorep.user.region_begin("region_name")
186
+
scorep.user.region_end("region_name")
187
+
```
188
+
189
+
User parameters can be used in any case:
190
+
191
+
```
192
+
scorep.user.parameter_int(name, val)
193
+
scorep.user.parameter_uint(name, val)
194
+
scorep.user.parameter_string(name, string)
195
+
```
196
+
197
+
where `name` defines the name of the parameter or region, while `val` or `string` represents the value that is passed to Score-P.
198
+
199
+
Disabeling the recording with Score-P is still also possilbe:
200
+
201
+
```
202
+
scorep.user.enable_recording()
203
+
scorep.user.disable_recording()
204
+
```
205
+
206
+
However, please be aware that the runtime impact of disabeling Score-P is rather small, as the instrumenter is still active. For details about the instrumenter, please see [Instrumenter](#Instrumenter).
207
+
187
208
## Overview about Flags
188
209
189
210
The following flags are special to the python bindings:
0 commit comments