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 -P preset
152 Specify a preset for a multi-run measurement, e.g., 'pop'. See
153 MULTI-RUN EXPERIMENTS below for details.
154 -L List all available multi-run presets.
156 -D config_file
158 Checks a multi-run config file for validity, if successful dumps
159 the processed configuration for comparison, and exits.
160
162 Environment variables with the 'SCAN_' prefix may be used to configure
163 the scan nexus itself (which is a serial workflow manager process),
164 rather than the instrumented application process(es) which will be
165 measured, which can also be configured via environment variables.
166 Configuration specified on the nexus command-line takes precedence over
167 that specified via environment variables. See MULTI-RUN EXPERIMENTS
168 below for details on interactions with configuration file settings.
169 Environment variables controlling scan
171 SCAN_ANALYZE_OPTS
172 Specifies trace analyzer options (default: none). For details on
173 the supported options, see scout(1).
174 SCAN_CLEAN
176 If enabled, removes event trace data after successful trace
177 analysis (default: 'false').
178 SCAN_MPI_LAUNCHER
180 Specifies a non-standard MPI launcher name.
181 SCAN_MPI_RANKS
183 Specifies the number of MPI processes, for example in an MPMD use
184 case or if the number of ranks is not automatically identified
185 correctly. The specified number will also be used in the
186 automatically generated experiment title. While an experiment title
187 with an incorrect number of processes is harmless (though generally
188 confusing), the correct number is required for automatic parallel
189 trace analysis.
190 SCAN_MULTIRUN_DEFAULT_CFG
192 Path to a multi-run configuration file that will be loaded per
193 default in any measurement based on configuration files or presets.
194 As a default settings file, only global settings are used to avoid
195 interference with explicitly specified configs or presets.
196 SCAN_MULTIRUN_PRESET_PATH
198 Colon-separated list of paths containing preset files.
199 SCAN_OVERWRITE
201 If enabled, removes an existing experiment archive directory before
202 measurement (default: 'false').
203 SCAN_SETENV
205 If environment variables are not automatically forwarded to MPI
206 processes by the launcher, one can specify the syntax that the
207 launcher requires for this as SCAN_SETENV. For example, "-foo"
208 results in passing "-foo key val" to the launcher, while "--foo="
209 results in "--foo key=val".
210 SCAN_TARGET
212 If there is an imposter executable or script, for example, used to
213 specify placement/thread binding, that precedes the instrumented
214 target, it may be necessary to explicitly identify the target
215 executable by setting SCAN_TARGET to the executable name.
216 SCAN_TRACE_ANALYZER
218 Specifies an alternative trace analyzer to be used (e.g., scout.mpi
219 or scout.hyb). If 'none' is specified, automatic trace analysis is
220 skipped after measurement.
221 SCAN_TRACE_FILESYS
223 Specifies an optional list of colon separated paths identifying
224 suitable file systems for tracing. If set, the file system of trace
225 measurements has to match at least one of the specified file
226 systems.
227 SCAN_WAIT
229 Time in seconds to wait for synchronization of a distributed
230 filesystem after measurement completion.
231 Common Score-P environment variables controlling the measurement
233 SCOREP_EXPERIMENT_DIRECTORY
234 Explicit experiment archive title.
235 SCOREP_ENABLE_PROFILING
237 Enable or disable runtime summarization.
238 SCOREP_ENABLE_TRACING
240 Enable or disable event trace generation.
241 SCOREP_FILTERING_FILE
243 Name of run-time measurement filter file.
244 SCOREP_VERBOSE
246 Controls the generation of additional (debugging) output from the
247 Score-P measurement system.
248 SCOREP_TOTAL_MEMORY
250 Size of per-process memory in bytes reserved for Score-P.
251 For further details, please refer to the Score-P documentation and/or
253 the output of 'scorep-info config-vars'.
254
256 scan also provides means to automate the generation of multiple
257 measurements with varying configuration settings. This workflow can be
258 employed for various analysis objectives, as long as the variations are
259 based on environment variables. Likely candidates are:
260 1. Increasing the statistical significance through multiple
262 repetitions of measurements with identical settings.
263 2. Spreading multiple hardware-counter measurements over different
265 runs to limit the measurement overhead and/or to overcome hardware
266 limitations (e.g., number of hardware performance counters that can
267 be measured simultaneously).
268 3. Performing a series of measurements with varying application
270 settings, like problem size or input data.
271 Results of such multi-run experiments can be used individually,
273 aggregated manually using various Cube tools, or be passed to the
274 square(1) command for automated report aggregation.
275 Attention:
277 The degree of non-determinism in an application's runtime behavior
278 will influence the informative value of any aggregated result. Only
279 with sufficient similarity between application runs will the
280 combination of results be useful.
281 Multi-run experiments are set up using a plain-text configuration file,
283 which is passed to the scan command via the -M command-line option. In
284 this file, the begin of each measurement run configuration is marked by
285 a line starting with a single dash (-) character; the remainder of the
286 line will be ignored. Subsequent lines up to either the next run
287 separator or the end of the file may contain at most one variable
288 setting of the form 'VARIABLE=VALUE'. Optionally, a section with global
289 settings can be specified at the beginning of the config file,
290 introduced by a line starting with two dashes (--); the remainder of
291 this line will again be ignored. A variable defined in the global
292 section will be applied in all subsequent run configurations unless it
293 is overwritten by a run-specific setting. The configuration file format
294 also allows for single-line comments starting with a hash character (#)
295 and blank lines, both of which are ignored.
296 For example, the following multi-run configuration file defines a
298 series of four subsequent measurements with different settings:
299 # example run configuration file
301 # global section
302 -- this can also hold comments
303 SCOREP_ENABLE_TRACING=true
304 -
305 # first run with two PAPI metrics
306 SCOREP_METRIC_PAPI=PAPI_TOT_CYC,PAPI_TOT_INS
307 -
308 # second run with different PAPI metric and increased Score-P memory
309 SCOREP_METRIC_PAPI=PAPI_LD_INS
310 SCOREP_TOTAL_MEMORY=42M
311 - third run with different PAPI metric
312 SCOREP_METRIC_PAPI=PAPI_VEC_DP
313 -
314 # fourth run using only global settings
315 Note that measurement configuration settings are not limited to scan or
317 Score-P environment variables, but also allow for setting arbitrary
318 variables in the measurement execution environment. Also, the order in
319 which measurements are specified may have an impact on the aggregated
320 result, see square(1) for details.
321 To ensure consistency and reproducibility, the environment must not
323 contain Score-P or Scalasca variables when using a multi-run
324 configuration file. Otherwise, scan will abort with an error providing
325 a list of the offending variables. That is, all Score-P/Scalasca
326 settings to be applied have to be placed in either the global or run-
327 specific sections of the configuration. Moreover, all variables used
328 anywhere in the configuration file will be unset before each
329 measurement run, and then set to either the global or run-specific
330 value if applicable, thus avoiding side effects from variable settings
331 not specified in the configuration file. The Score-P variable
332 SCOREP_EXPERIMENT_DIRECTORY will not have any effect inside the
333 configuration file, as an automatic naming scheme---an extension to the
334 default Scalasca scheme---is enforced to keep the multi-run measurement
335 directories consistent. To set the experiment directory a priori, the
336 scan command-line option -e can be used. Other scan options that
337 control the measurement (-q, -t, and -s) will be ignored when used with
338 a config file and should be set through the respective environment
339 variables in the configuration file for consistency.
340 A variation of the configuration file mode described above is the
342 preset mode. The preset mode combines predefined configurations for
343 typical scenarios with global environment variables for the specific
344 use case. In this case, only variables used in the preset configuration
345 are blocked in the global environment to avoid interference with the
346 functionality provided by the selected preset. Available presets can be
347 listed by using the -L option. By default, only presets provided by the
348 Scalasca installation are available. Additional presets can be provided
349 by adding paths to the SCAN_MULTIRUN_PRESET_PATH variable using a colon
350 as separator. Preset files have the extension .preset and follow the
351 same syntax as multi-run configuration files. To ensure the
352 functionality of a preset in the presence of additional user-defined
353 Score-P/Scalasca variables, the preset configuration file has to
354 contain all variables that may interfere with the functionality of the
355 preset by using default settings.
356 In addition to multi-run experiments with different configuration
358 settings, scan supports repeating a single or a set of measurements
359 multiple times via the -R command-line option, for example, to provide
360 increased statistical significance. For measurements without a
361 configuration file, the measurement will be repeated the requested
362 number of times with the current environment. In case of multi-run
363 configurations, each individual run will be repeated the given number
364 of times with the specified configuration.
365 For multi-run experiments, scan creates a common directory which
367 contains the result of each individual measurement run stored in a
368 subdirectory. The name of the base directory and the experiment
369 directories contains the number of configurations as well as the number
370 of repetitions. To support reproducibility, the configuration used is
371 stored in the file scalasca_run.cfg in the common base directory. To
372 test the validity of a configuration file before running a measurement,
373 scan provides the -D option. In this mode, the provided configuration
374 file is parsed and, on success, the processed data is dumped for
375 comparison.
376 To store commonly used system- or user-specific variables, the user can
378 specify a default configuration file via SCAN_MULTIRUN_DEFAULT_CFG. Its
379 global settings will be used in any configuration- or preset-based
380 multi-run measurement. Note that only the global settings are used to
381 avoid interference with explicitly specified files by adding additional
382 runs to the measurement.
383
385 scan exits with status 0 if measurement and automatic trace analysis
386 (if configured) were successful, and greater than 0 if errors occur.
387
389 While parsing the arguments, unrecognized flags might be reported as
390 ignored, and unrecognized options with required arguments might need to
391 be quoted.
392 Instrumented applications can still be run without using scan to
394 generate measurements, however, measurement configuration is then
395 exclusively via Score-P environment variables (which must be explicitly
396 exported to MPI processes) and trace analysis is not automatically
397 started after event trace collection.
398
400 Please report bugs to scalasca@fz-juelich.de. Make sure to include at
401 least the following information in your bug report:
402 • The Scalasca Trace Tools version reported by 'scalasca -V'.
404 • The Scalasca Trace Tools configuration reported by 'scalasca -c'.
406 • The Score-P version reported by 'scorep --version'.
408 • The Score-P configuration reported by 'scorep-info config-summary'.
410 • The exact command line of the failing command.
412 • The exact failure/error message.
414 Also, if the trace analysis fails, please archive a copy of the entire
416 experiment archive directory including the event trace data, as this
417 may be required to aid in debugging. However, ONLY PROVIDE TRACE DATA
418 IF EXPLICITLY REQUESTED, as the data volume may be excessive.
419
421 scan mpiexec -n 4 foo args
422 Execute the instrumented MPI program foo with command-line arguments
423 args, collecting a runtime summary (default). Results in an experiment
424 directory scorep_foo_4_sum.
425 OMP_NUM_THREADS=3 scan -s mpiexec -n 4 foobar
427 Execute the instrumented hybrid MPI+OpenMP program foobar, collecting a
428 runtime summary (default, but explicitly requested). Results in an
429 experiment directory scorep_foobar_4x3_sum.
430 OMP_NUM_THREADS=3 scan -q -t -f filter bar
432 Execute the instrumented OpenMP program bar, collecting only an event
433 trace with the run-time measurement filter filter applied. Trace
434 collection is immediately followed by Scalasca's automatic trace
435 analysis. Results in an experiment directory scorep_bar_Ox3_trace.
436
438 scalasca(1), square(1), scout(1)
439 The Score-P instrumentation and measurement system documentation is
441 available online at https://www.score-p.org.
442 The full Scalasca Trace Tools documentation is available online at
444 https://www.scalasca.org.
445Version 2.6 Mon Apr 19 2021 scan(1)