1scan(1)                      Scalasca Trace Tools                      scan(1)
2
3
4

NAME

6       scan - Scalasca measurement collection and analysis nexus
7

SYNOPSIS

9       scan [OPTIONS] [LAUNCHER [LAUNCHER_ARGS]] TARGET [TARGET_ARGS]
10

DESCRIPTION

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
18       • Measurement configuration
19
20       • Application execution using any given arguments TARGET_ARGS
21
22       • Collection of measured data
23
24       • Automatic post-mortem trace analysis (if configured)
25
26       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
34       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
42       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
55       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
64       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
69       • MANIFEST.md: a text file briefly describing  the  directory  contents
70         produced by the Score-P measurement system
71
72       • scorep.cfg: a copy of the measurement configuration
73
74       • scorep.log: the measurement log file
75
76       • scorep.filter: a copy of the measurement filter (if provided)
77
78       In  runtime  summarization  mode,  the  archive  directory additionally
79       contains:
80
81       • profile.cubex: the runtime summary result
82
83       In trace collection and analysis mode, the following  additional  files
84       are generated:
85
86       • an OTF2 trace archive consisting of
87
88         • the anchor file traces.otf2,
89
90         • the global definitions file traces.def, and
91
92         • the per-process data files in the traces/ directory
93
94       • scout.log: the trace analysis log file
95
96       • scout.cubex: the trace analysis result
97
98       • trace.stat: trace analysis pattern statistics
99
100       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
104       • scalasca_run.cfg:  a  (possibly auto-generated) copy of the multi-run
105         configuration specification file
106

OPTIONS

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
114       -h  Print a brief usage summary, then exit.
115
116       -v  Increase verbosity.
117
118       -n  Print the command(s) to be launched, but do not execute them.
119
120       -q  Quiescent execution with neither summarization nor tracing enabled.
121           Sets  both  SCOREP_ENABLE_PROFILING  and  SCOREP_ENABLE_TRACING  to
122           'false'.
123
124       -s  Enable runtime summarization mode. Sets SCOREP_ENABLE_PROFILING  to
125           'true'. This is the default.
126
127       -t  Enable trace collection and analysis. Sets SCOREP_ENABLE_TRACING to
128           'true'.
129
130       -a  Skip measurement step to (re-)analyze an existing trace.
131
132       -e experiment_dir
133           Override default experiment archive name to generate and/or analyze
134           experiment_dir. Sets SCOREP_EXPERIMENT_DIRECTORY.
135
136       -f filter_file
137           Use   the   measurement   filter   rules   from  filter_file.  Sets
138           SCOREP_FILTERING_FILE.
139
140       -l lock_file
141           Block start of measurement while lock_file exists.
142
143       -R num_runs
144           Specifies   the   number   measurement   runs   per   configuration
145           (default=1).
146
147       -M config_file
148           Allows   to  specify  a  configuration  file  describing  multi-run
149           experiment settings. See MULTI-RUN EXPERIMENTS below for details.
150
151       -P preset
152           Specify a preset for a  multi-run  measurement,  e.g.,  'pop'.  See
153           MULTI-RUN EXPERIMENTS below for details.
154
155       -L  List all available multi-run presets.
156
157       -D config_file
158           Checks  a  multi-run  config file for validity, if successful dumps
159           the processed configuration for comparison, and exits.
160

ENVIRONMENT

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
170   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
175       SCAN_CLEAN
176           If  enabled,  removes  event  trace  data  after  successful  trace
177           analysis (default: 'false').
178
179       SCAN_MPI_LAUNCHER
180           Specifies a non-standard MPI launcher name.
181
182       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
191       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
197       SCAN_MULTIRUN_PRESET_PATH
198           Colon-separated list of paths containing preset files.
199
200       SCAN_OVERWRITE
201           If enabled, removes an existing experiment archive directory before
202           measurement (default: 'false').
203
204       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
211       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
217       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
222       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
228       SCAN_WAIT
229           Time in seconds  to  wait  for  synchronization  of  a  distributed
230           filesystem after measurement completion.
231
232   Common Score-P environment variables controlling the measurement
233       SCOREP_EXPERIMENT_DIRECTORY
234           Explicit experiment archive title.
235
236       SCOREP_ENABLE_PROFILING
237           Enable or disable runtime summarization.
238
239       SCOREP_ENABLE_TRACING
240           Enable or disable event trace generation.
241
242       SCOREP_FILTERING_FILE
243           Name of run-time measurement filter file.
244
245       SCOREP_VERBOSE
246           Controls  the  generation of additional (debugging) output from the
247           Score-P measurement system.
248
249       SCOREP_TOTAL_MEMORY
250           Size of per-process memory in bytes reserved for Score-P.
251
252       For further details, please refer to the Score-P  documentation  and/or
253       the output of 'scorep-info config-vars'.
254

MULTI-RUN EXPERIMENTS

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
261       1.  Increasing   the   statistical   significance   through    multiple
262           repetitions of measurements with identical settings.
263
264       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
269       3.  Performing  a  series  of  measurements  with  varying  application
270           settings, like problem size or input data.
271
272       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
276       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
282       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
297       For  example,  the  following  multi-run  configuration  file defines a
298       series of four subsequent measurements with different settings:
299
300           # 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
316       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
322       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
341       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
357       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
366       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
377       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

EXIT STATUS

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

NOTES

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
393       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

BUGS

400       Please  report  bugs to scalasca@fz-juelich.de. Make sure to include at
401       least the following information in your bug report:
402
403       • The Scalasca Trace Tools version reported by 'scalasca -V'.
404
405       • The Scalasca Trace Tools configuration reported by 'scalasca -c'.
406
407       • The Score-P version reported by 'scorep --version'.
408
409       • The Score-P configuration reported by 'scorep-info config-summary'.
410
411       • The exact command line of the failing command.
412
413       • The exact failure/error message.
414
415       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

EXAMPLES

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
426       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
431       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

SEE ALSO

438       scalasca(1), square(1), scout(1)
439
440       The Score-P instrumentation and  measurement  system  documentation  is
441       available online at https://www.score-p.org.
442
443       The  full  Scalasca  Trace  Tools  documentation is available online at
444       https://www.scalasca.org.
445
446Version 2.6.1                   Wed Dec 14 2022                        scan(1)
Impressum