doc: promote sections in projections manual
[charm.git] / doc / projections / tracing.tex
1 \projections{} is a performance analysis/visualization framework that
2 helps you understand and investigate performance-related problems in
3 your parallel (\charmpp{}) application. It is a framework with an
4 event tracing component with features that allow you to control the
5 amount of information generated and to a lesser degree the amount of
6 perturbation the tracing activities introduce into the application. It
7 also has a Java-based visualization and analysis component with
8 various views that will help present the performance information in a
9 visually useful manner.
10
11 Performance analysis with \projections{} typically involves 2 simple
12 steps:
13
14 \begin{enumerate}
15 \item 
16 Prepare your application code by linking with the appropriate trace
17 generation modules and executing it to generate trace data.
18 \item
19 Using the Java-based tool to visually study various aspects of the
20 performance information to locate application execution performance
21 problems.
22 \end{enumerate}
23
24 The \charmpp{} runtime automatically records pertinent performance
25 data at performance-related events encountered by the runtime. These
26 events include the start and end of entry method execution, message
27 sends from entry methods and scheduler idle time. This means {\em
28 most} users will not need to manually insert code into their
29 applications in order to generate trace data. In scenarios where
30 special performance information not captured by the runtime is
31 required, an API (see section \ref{sec::api}) is available for
32 user-specific events with some support for visualization by the
33 Java-based tool. If greater control over tracing activities
34 (e.g. dynamically turning instrumentation on and off) is desired, the
35 API also allows users to insert code into their applications for such
36 purposes.
37
38 The automatic recording of events by the \projections{} framework
39 introduces the overhead of an if-statement for each runtime event,
40 even if no performance analysis traces are desired. Developers of
41 \charmpp{} applications who consider such an overhead to be
42 unacceptable (e.g. for a production application which requires the
43 absolute best performance) may recompile the \charmpp{} runtime with
44 the {\tt -{}-with-production} flag which removes the instrumentation
45 stubs.
46
47 To enable performance tracing of your application, users simply need
48 to link the appropriate trace data generation module(s) (also referred
49 to as {\em tracemode(s)}). (see section \ref{sec::trace modules})
50
51 \section{Enabling Performance Tracing at Link/Run Time}
52 \label{sec::trace modules}
53
54 \projections{} tracing modules dictate the type of performance data,
55 data detail and data format each processor will record. They are also
56 refered to as ``tracemodes''. There are currently 2 tracemodes
57 available. Zero or more tracemodes may be specified at link-time. When
58 no tracemodes are specified, no trace data is generated.
59
60 \subsection{Tracemode {\tt projections}}
61
62 Link time option: {\tt -tracemode projections}
63
64 This tracemode generates detailed event log files that contain
65 information about all \charmpp{} events like entry method calls and
66 message packing during the execution of the program.  The data will be
67 used by \projections{} in visualization and analysis.
68
69 This tracemode will generate a single symbol table file and $p$ ASCII
70 log files for $p$ processors. The names of the log files will be
71 NAME.\#.log where NAME is the name of your executable and \# is the
72 processor \#. The name of the symbol table file is NAME.sts where NAME
73 is the name of your executable.
74
75 This is the main source of data expected by the performance
76 visualizer. Certain tools like timeline will not work without the
77 detailed data from this tracemode.
78
79 The following is a list of runtime options available under this tracemode:
80
81 \begin{itemize}
82 \item
83 {\tt +logsize NUM}: keep only NUM log entries in the memory of each
84 processor. The logs are emptied and flushed to disk when filled.
85 \item
86 {\tt +binary-trace}:  generate projections log in binary form.
87 \item
88 {\tt +gz-trace}:      generate gzip (if available) compressed log files.
89 \item
90 {\tt +checknested}: a debug option. Checks if events are improperly nested
91 while recorded and issue a warning immediately.
92
93 \item {\tt +trace-subdirs NUM}: divide the generated log files among
94   {\tt NUM} subdirectories of the trace root, each named {\tt
95     PROGNAME.projdir.K}
96 \end{itemize}
97
98 \subsection{Tracemode {\tt summary}}
99
100 Compile option: {\tt -tracemode summary}
101
102 In this tracemode, execution time across all entry points for each
103 processor is partitioned into a fixed number of equally sized
104 time-interval bins. These bins are globally resized whenever they are
105 all filled in order to accomodate longer execution times while keeping
106 the amount of space used constant.
107
108 Additional data like the total number of calls made to each entry
109 point is summarised within each processor.
110
111 This tracemode will generate a single symbol table file and $p$ ASCII
112 summary files for $p$ processors. The names of the summary files will
113 be NAME.\#.sum where NAME is the name of your executable and \# is the
114 processor \#. The name of the symbol table file is NAME.sum.sts where NAME
115 is the name of your executable.
116
117 This tracemode can be used to control the amount of output generated
118 in a run. It is typically used in scenarios where a quick look at the
119 overall utilization graph of the application is desired to identify
120 smaller regions of time for more detailed study. Attempting to
121 generate the same graph using the detailed logs of the prior tracemode
122 may be unnecessarily time consuming or impossible.
123
124 The following is a list of runtime options available under this tracemode:
125
126 \begin{itemize}
127 \item
128 {\tt +bincount NUM}:   use NUM time-interval bins. The bins are resized and compacted when filled.
129 \item
130 {\tt +binsize TIME}:   sets the initial time quantum each bin represents.
131 \item
132 {\tt +version}:        set summary version to generate.
133 %\item
134 %{\tt +epThreshold}: DOESNT DO ANYTHING YET. LEFT COMMENTED FOR DOC PURPOSES
135 %\item
136 %{\tt +epInterval}: DOESNT DO ANYTHING YET. LEFT COMMENTED FOR DOC PURPOSES
137 \item
138 {\tt +sumDetail}: Generates a additional set of files, one per processor,
139 that stores the time spent by each entry method associated with each 
140 time-bin. The names of ``summary detail'' files will be NAME.\#.sumd where
141 NAME is the name of your executable and \# is the processor \#.
142 \item
143 {\tt +sumOnly}: Generates an additional file that stores a single
144 utilization value per time-bin, averaged across all processors. This
145 file bears the name NAME.sum where NAME is the name of your
146 executable. This runtime option currently overrides the {\tt
147 +sumDetail} option.
148 \end{itemize}
149
150 \subsection{General Runtime Options}
151 \label{sec::general options}
152
153 The following is a list of runtime options available with the same
154 semantics for all tracemodes:
155
156 \begin{itemize}
157 \item
158 {\tt +traceroot DIR}: place all generated files in DIR.
159 \item
160 {\tt +traceoff}: trace generation is turned off when the application
161 is started. The user is expected to insert code to turn tracing on at
162 some point in the run.
163 \item
164 {\tt +traceWarn}: By default, warning messages from the framework are
165 not displayed. This option enables warning messages to be printed to
166 screen. However, on large numbers of processors, they can overwhelm
167 the terminal I/O system of the machine and result in unacceptable
168 perturbation of the application.
169 \end{itemize}
170
171 \subsection{End-of-run Analysis for Data Reduction}
172 \label{sec::data reduction}
173
174 As applications are scaled to thousands or hundreds of thousands of
175 processors, the amount of data generated becomes extremely large and
176 potentially unmanagable by the visualization tool. At the time of this
177 documentation, \projections{} is capable of handling data from 8000+
178 processors but with somewhat severe tool responsiveness issues. We
179 have developed an approach to mitigate this data size problem with
180 options to trim-off ``uninteresting'' processors' data by not writing
181 such data at the end of an application's execution.
182
183 This is currently done through heuristics to pick out interesting
184 extremal (i.e. poorly behaved) processors and at the same time using a
185 k-means clustering to pick out exemplar processors from equivalence
186 classes to form a representative subset of processor data. The analyst
187 is advised to also link in the summary module via {\tt +tracemode
188 summary} and enable the {\tt +sumDetail} option in order to retain
189 some profile data for processors whose data were dropped.
190
191 \begin{itemize}
192 \item
193 {\tt +extrema}: enables extremal processor identification analysis at
194 the end of the application's execution.
195 \item
196 {\tt +numClusters}: determines the number of clusters (equivalence
197 classes) to be used by the k-means clustering algorithm for
198 determining exemplar processors. Analysts should take advantage of
199 their knowledge of natural application decomposition to guess at a
200 good value for this.
201 \end{itemize}
202
203 This feature is still being developed and refined as part of our
204 research. It would be appreciated if users of this feature could
205 contact the developers if you have input or suggestions.
206
207
208 \section{Tracing API for \charmpp{} Applications}
209 \label{sec::api}
210
211 \subsection{Selective Tracing}
212 \label{sec::selective tracing}
213
214 \charmpp{} allows user to start/stop tracing the execution at certain
215 points in time on the local processor. Users are advised to make these
216 calls on all processors and at well-defined points in the application.
217
218 Users may choose to have instrumentation turned off at first (by
219 command line option {\tt +traceoff} - see section \ref{sec::general options}) if some period of time in middle of the
220 application\'s execution is of interest to the user.
221
222 Alternatively, users may start the application with instrumentation
223 turned on (default) and turn off tracing for specific sections of the
224 application.
225
226 Again, users are advised to be consistent as the {\tt +traceoff}
227 runtime option applies to all processors in the application.
228
229 \begin{itemize}
230 \item
231 {\tt void traceBegin()}
232
233 Enables the runtime to trace events (including all user events) on the local processor where {\tt traceBegin} is called.
234
235 \item
236 {\tt void traceEnd()}
237
238 Prevents the runtime from tracing events (including all user events) on the local processor where {\tt traceEnd} is called.
239
240 \end{itemize}
241
242 \subsection{User Events}
243 \label{sec::user events}
244
245 \projections{} has the ability to visualize traceable user
246 specified events. User events are usually displayed in the Timeline view as vertical bars above the entry methods. Alternatively the user event can be displayed as a vertical bar that vertically spans the timelines for all processors. Follow these following basic steps for creating user events in a charm++ program:
247
248 \begin{enumerate}
249 \item
250 Register an event with an identifying string and either specify or acquire
251 a globally unique event identifier. All user events that are not registered will be displayed in white.
252
253 \item
254 Use the event identifier to specify trace points in your code of interest to you.
255 \end{enumerate}
256
257 The functions available are as follows:
258
259 \begin{itemize}
260 \item
261 {\tt int traceRegisterUserEvent(char* EventDesc, int EventNum=-1) }
262
263 This function registers a user event by associating {\tt EventNum} to
264 {\tt EventDesc}. If {\tt EventNum} is not specified, a globally unique
265 event identifier is obtained from the runtime and returned. The string {\tt EventDesc} must either be a constant string, or it can be a dynamically allocated string that is {\bf NOT} freed by the program. If the {\tt EventDesc} contains a substring ``***'' then the Projections Timeline tool will draw the event vertically spanning all PE timelines.
266
267 {\tt EventNum} has to be the same on all processors. Therefore use one of the following methods to ensure the same value for any PEs generating the user events:
268
269 \begin{enumerate}
270 \item
271 Call {\tt traceRegisterUserEvent} on PE 0 in main::main without specifying
272 an event number, and store returned event number into a readonly variable.
273 \item
274 Call {\tt traceRegisterUserEvent} and specify the event number on
275 processor 0. Doing this on other processors would have no
276 effect. Afterwards, the event number can be used in the following user
277 event calls.
278 \end{enumerate}
279
280 Eg. {\tt traceRegisterUserEvent("Time Step Begin", 10);}
281
282 Eg. {\tt eventID = traceRegisterUserEvent(``Time Step Begin'');}
283
284 \end{itemize}
285
286
287
288 There are two main types of user events, bracketed and non bracketed. Non-bracketed user events mark a specific point in time. Bracketed user events span an arbitrary contiguous time range. Additionally, the user can supply a short user supplied text string that is recorded with the event in the log file. These strings should not contain newline characters, but they may contain simple html formatting tags such as \texttt{<br>}, \texttt{<b>}, \texttt{<i>}, \texttt{<font color=\#ff00ff>}, etc.
289
290 The calls for recording user events are the following:
291
292 \begin{itemize}
293
294
295 \item
296 {\tt void traceUserEvent(int EventNum) }
297
298 This function creates a user event that marks a specific point in time.
299
300 Eg. {\tt traceUserEvent(10);}
301
302 \item
303 {\tt void traceUserBracketEvent(int EventNum, double StartTime, double EndTime) }
304
305 This function records a user event spanning a time interval from {\tt StartTime} to {\tt EndTime}. Both {\tt StartTime} and {\tt EndTime} should be obtained from a call to {\tt CmiWallTimer()} at the appropriate point in the program.
306
307 Eg.
308 \begin{verbatim}
309    traceRegisterUserEvent("Critical Code", 20); // on PE 0
310    double critStart = CmiWallTimer();;  // start time
311    // do the critical code
312    traceUserBracketEvent(20, critStart,CmiWallTimer());
313 \end{verbatim}
314
315 \item
316 {\tt void traceUserSuppliedNote(char * note) }
317
318 This function records a user specified text string at the current time.
319
320 \item
321 {\tt void traceUserSuppliedBracketedNote(char *note, int EventNum, double StartTime, double EndTime)}
322
323 This function records a user event spanning a time interval from {\tt StartTime} to {\tt EndTime}. Both {\tt StartTime} and {\tt EndTime} should be obtained from a call to {\tt CmiWallTimer()} at the appropriate point in the program.
324
325 Additionally, a user supplied text string is recorded, and the  {\tt EventNum} is recorded. These events are therefore displayed with colors determined by the {\tt EventNum}, just as those generated with {\tt traceUserBracketEvent} are.
326
327 \end{itemize}
328