1scan(1) Scalasca Trace Tools scan(1)
2
6 scan - Scalasca measurement collection and analysis nexus
7
9 scan [OPTIONS] [LAUNCHER [LAUNCHER_ARGS]] TARGET [TARGET_ARGS]
10
12 scan, the Scalasca measurement collection and analysis nexus, manages
13 the configuration and processing of performance experiments with an
14 executable TARGET. TARGET needs to be instrumented beforehand using the
15 Score-P instrumentation and measurement system. In particular, scan
16 integrates the following steps:
17 · Measurement configuration
19 · Application execution using any given arguments TARGET_ARGS
21 · Collection of measured data
23 · Automatic post-mortem trace analysis (if configured)
25 Many different experiments can typically be performed with a single
27 instrumented executable without needing to re-instrument, by using
28 different measurement and analysis configurations. The default runtime
29 summarization mode directly produces an analysis report for
30 examination, whereas event trace collection and analysis are
31 automatically done in two steps to produce a profile augmented with
32 additional metrics.
33 Serial and multi-threaded programs are typically launched directly,
35 whereas MPI and hybrid MPI+X programs usually require a special
36 LAUNCHER command such as mpiexec, which may need additional arguments
37 LAUNCHER_ARGS (e.g., to specify the number of processes to be created).
38 scan automatically recognizes many MPI launchers, but if not, the MPI
39 launcher name can be specified using the environment variable
40 SCAN_MPI_LAUNCHER (see ENVIRONMENT).
41 scan examines the executable TARGET to determine whether Score-P
43 instrumentation is present; otherwise the measurement is aborted. The
44 number of MPI processes and OpenMP threads are determined from
45 LAUNCHER_ARGS and/or the environment. If the target executable is not
46 specified as one of the launcher arguments, it is expected to be the
47 immediately following part of the command line. It may be necessary to
48 use a double-dash specification (--) to explicitly separate the target
49 from the preceding launcher specification. If there is an imposter
50 executable or script, e.g., often used to specify placement/thread
51 binding, that precedes the instrumented TARGET, it may be necessary to
52 explicitly identify the target with the environment variable
53 SCAN_TARGET (see ENVIRONMENT).
54 A unique directory is created for each measurement experiment, which
56 must not already exist when measurement starts unless SCAN_OVERWRITE is
57 enabled (see ENVIRONMENT); otherwise measurement is aborted. A default
58 name for each measurement archive directory is created from a 'scorep_'
59 prefix, the name of the executable TARGET, the run configuration (e.g.,
60 number of processes specified), and the measurement configuration. This
61 default name can be overwritten using the SCOREP_EXPERIMENT_DIRECTORY
62 environment variable (see ENVIRONMENT) or the -e command-line option.
63 When measurement has completed, the measurement archive directory
65 contains all artifacts produced by the measurement and subsequent trace
66 analysis (if configured). In particular, the following files are
67 produced independent from the selected measurement mode:
68 · MANIFEST.md: a text file briefly describing the directory contents
70 produced by the Score-P measurement system
71 · scorep.cfg: a copy of the measurement configuration
73 · scorep.log: the measurement log file
75 · scorep.filter: a copy of the measurement filter (if provided)
77 In runtime summarization mode, the archive directory additionally
79 contains:
80 · profile.cubex: the runtime summary result
82 In trace collection and analysis mode, the following additional files
84 are generated:
85 · an OTF2 trace archive consisting of
87 · the anchor file traces.otf2,
89 · the global definitions file traces.def, and
91 · the per-process data files in the traces/ directory
93 · scout.log: the trace analysis log file
95 · scout.cubex: the trace analysis result
97 · trace.stat: trace analysis pattern statistics
99 In multi-run mode, the results of the individual runs are stored in
101 subdirectories inside the top-level measurement archive directory. In
102 addition, the following file will be archived:
103 · scalasca_run.cfg: a (possibly auto-generated) copy of the multi-run
105 configuration specification file
106
108 The scan command accepts the following command-line options. Note that
109 configuration settings specified on the command line take precedence
110 over those specified via environment variables (see ENVIRONMENT). Also,
111 see MULTI-RUN EXPERIMENTS below for details on interactions with
112 configuration file settings.
113 -h Print a brief usage summary, then exit.
115 -v Increase verbosity.
117 -n Print the command(s) to be launched, but do not execute them.
119 -q Quiescent execution with neither summarization nor tracing enabled.
121 Sets both SCOREP_ENABLE_PROFILING and SCOREP_ENABLE_TRACING to
122 'false'.
123 -s Enable runtime summarization mode. Sets SCOREP_ENABLE_PROFILING to
125 'true'. This is the default.
126 -t Enable trace collection and analysis. Sets SCOREP_ENABLE_TRACING to
128 'true'.
129 -a Skip measurement step to (re-)analyze an existing trace.
131 -e experiment_dir
133 Override default experiment archive name to generate and/or analyze
134 experiment_dir. Sets SCOREP_EXPERIMENT_DIRECTORY.
135 -f filter_file
137 Use the measurement filter rules from filter_file. Sets
138 SCOREP_FILTERING_FILE.
139 -l lock_file
141 Block start of measurement while lock_file exists.
142 -R num_runs
144 Specifies the number measurement runs per configuration
145 (default=1).
146 -M config_file
148 Allows to specify a configuration file describing multi-run
149 experiment settings. See MULTI-RUN EXPERIMENTS below for details.
150
152 Environment variables with the 'SCAN_' prefix may be used to configure
153 the scan nexus itself (which is a serial workflow manager process),
154 rather than the instrumented application process(es) which will be
155 measured, which can also be configured via environment variables.
156 Configuration specified on the nexus command-line takes precedence over
157 that specified via environment variables. See MULTI-RUN EXPERIMENTS
158 below for details on interactions with configuration file settings.
159 Environment variables controlling scan
161 SCAN_ANALYZE_OPTS
162 Specifies trace analyzer options (default: none). For details on
163 the supported options, see scout(1).
164 SCAN_CLEAN
166 If enabled, removes event trace data after successful trace
167 analysis (default: 'false').
168 SCAN_MPI_LAUNCHER
170 Specifies a non-standard MPI launcher name.
171 SCAN_MPI_RANKS
173 Specifies the number of MPI processes, for example in an MPMD use
174 case or if the number of ranks is not automatically identified
175 correctly. The specified number will also be used in the
176 automatically generated experiment title. While an experiment title
177 with an incorrect number of processes is harmless (though generally
178 confusing), the correct number is required for automatic parallel
179 trace analysis.
180 SCAN_OVERWRITE
182 If enabled, removes an existing experiment archive directory before
183 measurement (default: 'false').
184 SCAN_SETENV
186 If environment variables are not automatically forwarded to MPI
187 processes by the launcher, one can specify the syntax that the
188 launcher requires for this as SCAN_SETENV. For example, "-foo"
189 results in passing "-foo key val" to the launcher, while "--foo="
190 results in "--foo key=val".
191 SCAN_TARGET
193 If there is an imposter executable or script, for example, used to
194 specify placement/thread binding, that precedes the instrumented
195 target, it may be necessary to explicitly identify the target
196 executable by setting SCAN_TARGET to the executable name.
197 SCAN_TRACE_ANALYZER
199 Specifies an alternative trace analyzer to be used (e.g., scout.mpi
200 or scout.hyb). If 'none' is specified, automatic trace analysis is
201 skipped after measurement.
202 SCAN_WAIT
204 Time in seconds to wait for synchronization of a distributed
205 filesystem after measurement completion.
206 Common Score-P environment variables controlling the measurement
208 SCOREP_EXPERIMENT_DIRECTORY
209 Explicit experiment archive title.
210 SCOREP_ENABLE_PROFILING
212 Enable or disable runtime summarization.
213 SCOREP_ENABLE_TRACING
215 Enable or disable event trace generation.
216 SCOREP_FILTERING_FILE
218 Name of run-time measurement filter file.
219 SCOREP_VERBOSE
221 Controls the generation of additional (debugging) output from the
222 Score-P measurement system.
223 SCOREP_TOTAL_MEMORY
225 Size of per-process memory in bytes reserved for Score-P.
226 For further details, please refer to the Score-P documentation and/or
228 the output of 'scorep-info config-vars'.
229
231 scan also provides means to automate the generation of multiple
232 measurements with varying configuration settings. This workflow can be
233 employed for various analysis objectives, as long as the variations are
234 based on environment variables. Likely candidates are:
235 1. Increasing the statistical significance through multiple
237 repetitions of measurements with identical settings.
238 2. Spreading multiple hardware-counter measurements over different
240 runs to limit the measurement overhead and/or to overcome hardware
241 limitations (e.g., number of hardware performance counters that can
242 be measured simultaneously).
243 3. Performing a series of measurements with varying application
245 settings, like problem size or input data.
246 Results of such multi-run experiments can be used individually,
248 aggregated manually using various Cube tools, or be passed to the
249 square(1) command for automated report aggregation.
250 Attention:
252 The degree of non-determinism in an application's runtime behavior
253 will influence the informative value of any aggregated result. Only
254 with sufficient similarity between application runs will the
255 combination of results be useful.
256 Multi-run experiments are set up using a plain-text configuration file,
258 which is passed to the scan command via the -M command-line option. In
259 this file, the begin of each measurement run configuration is marked by
260 a line starting with a single dash (-) character; the remainder of the
261 line will be ignored. Subsequent lines up to either the next run
262 separator or the end of the file may contain at most one variable
263 setting of the form 'VARIABLE=VALUE'. Optionally, a section with global
264 settings can be specified at the beginning of the config file,
265 introduced by a line starting with two dashes (--); the remainder of
266 this line will again be ignored. A variable defined in the global
267 section will be applied in all subsequent run configurations unless it
268 is overwritten by a run-specific setting. The configuration file format
269 also allows for single-line comments starting with a hash character (#)
270 and blank lines, both of which are ignored.
271 For example, the following multi-run configuration file defines a
273 series of four subsequent measurements with different settings:
274 # example run configuration file
276 # global section
277 -- this can also hold comments
278 SCOREP_ENABLE_TRACING=true
279 -
280 # first run with two PAPI metrics
281 SCOREP_METRIC_PAPI=PAPI_TOT_CYC,PAPI_TOT_INS
282 -
283 # second run with different PAPI metric and increased Score-P memory
284 SCOREP_METRIC_PAPI=PAPI_LD_INS
285 SCOREP_TOTAL_MEMORY=42M
286 - third run with different PAPI metric
287 SCOREP_METRIC_PAPI=PAPI_VEC_DP
288 -
289 # fourth run using only global settings
290 Note that measurement configuration settings are not limited to scan or
292 Score-P environment variables, but also allow for setting arbitrary
293 variables in the measurement execution environment. Also, the order in
294 which measurements are specified may have an impact on the aggregated
295 result, see square(1) for details.
296 To ensure consistency and reproducibility, the environment must not
298 contain Score-P or Scalasca variables when using a multi-run
299 configuration file. Otherwise, scan will abort with an error providing
300 a list of the offending variables. That is, all Score-P/Scalasca
301 settings to be applied have to be placed in either the global or run-
302 specific sections of the configuration. Moreover, all variables used
303 anywhere in the configuration file will be unset before each
304 measurement run, and then set to either the global or run-specific
305 value if applicable, thus avoiding side effects from variable settings
306 not specified in the configuration file. The Score-P variable
307 SCOREP_EXPERIMENT_DIRECTORY will not have any effect inside the
308 configuration file, as an automatic naming scheme---an extension to the
309 default Scalasca scheme---is enforced to keep the multi-run measurement
310 directories consistent. To set the experiment directory a priori, the
311 scan command-line option -e can be used. Other scan options that
312 control the measurement (-q, -t, and -s) will be ignored when used with
313 a config file and should be set through the respective environment
314 variables in the configuration file for consistency.
315 In addition to multi-run experiments with different configuration
317 settings, scan supports repeating a single or a set of measurements
318 multiple times via the -R command-line option, for example, to provide
319 increased statistical significance. For measurements without a
320 configuration file, the measurement will be repeated the requested
321 number of times with the current environment. In case of multi-run
322 configurations, each individual run will be repeated the given number
323 of times with the specified configuration.
324 For multi-run experiments, scan creates a common directory which
326 contains the result of each individual measurement run stored in a
327 subdirectory. The name of the base directory and the experiment
328 directories contains the number of configurations as well as the number
329 of repetitions. To support reproducibility, the configuration used is
330 stored in the file scalasca_run.cfg in the common base directory.
331
333 scan exits with status 0 if measurement and automatic trace analysis
334 (if configured) were successful, and greater than 0 if errors occur.
335
337 While parsing the arguments, unrecognized flags might be reported as
338 ignored, and unrecognized options with required arguments might need to
339 be quoted.
340 Instrumented applications can still be run without using scan to
342 generate measurements, however, measurement configuration is then
343 exclusively via Score-P environment variables (which must be explicitly
344 exported to MPI processes) and trace analysis is not automatically
345 started after event trace collection.
346
348 Please report bugs to scalasca@fz-juelich.de. Make sure to include at
349 least the following information in your bug report:
350 · The Scalasca Trace Tools version reported by 'scalasca -V'.
352 · The Scalasca Trace Tools configuration reported by 'scalasca -c'.
354 · The Score-P version reported by 'scorep --version'.
356 · The Score-P configuration reported by 'scorep-info config-summary'.
358 · The exact command line of the failing command.
360 · The exact failure/error message.
362 Also, if the trace analysis fails, please archive a copy of the entire
364 experiment archive directory including the event trace data, as this
365 may be required to aid in debugging. However, ONLY PROVIDE TRACE DATA
366 IF EXPLICITLY REQUESTED, as the data volume may be excessive.
367
369 scan mpiexec -n 4 foo args
370 Execute the instrumented MPI program foo with command-line arguments
371 args, collecting a runtime summary (default). Results in an experiment
372 directory scorep_foo_4_sum.
373 OMP_NUM_THREADS=3 scan -s mpiexec -n 4 foobar
375 Execute the instrumented hybrid MPI+OpenMP program foobar, collecting a
376 runtime summary (default, but explicitly requested). Results in an
377 experiment directory scorep_foobar_4x3_sum.
378 OMP_NUM_THREADS=3 scan -q -t -f filter bar
380 Execute the instrumented OpenMP program bar, collecting only an event
381 trace with the run-time measurement filter filter applied. Trace
382 collection is immediately followed by Scalasca's automatic trace
383 analysis. Results in an experiment directory scorep_bar_Ox3_trace.
384
386 scalasca(1), square(1), scout(1)
387 The Score-P instrumentation and measurement system documentation is
389 available online at https://www.score-p.org.
390 The full Scalasca Trace Tools documentation is available online at
392 https://www.scalasca.org.
393Version 2.5 Fri Mar 22 2019 scan(1)