You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openoffice.apache.org by wa...@apache.org on 2012/01/10 17:18:32 UTC
svn commit: r1229624 [2/2] - in /incubator/ooo/ooo-site/trunk/content/tools:
./ moz_prebuild/ moz_prebuild/680/ moz_prebuild/OOo3.1/
moz_prebuild/OOo3.2/ profiling/ profiling/pod/ profiling/pod/LogFile/
Added: incubator/ooo/ooo-site/trunk/content/tools/profiling/profiling-howto.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/profiling/profiling-howto.html?rev=1229624&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/tools/profiling/profiling-howto.html (added)
+++ incubator/ooo/ooo-site/trunk/content/tools/profiling/profiling-howto.html Tue Jan 10 16:18:19 2012
@@ -0,0 +1,202 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<head>
+ <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
+ <TITLE></TITLE>
+ <META NAME="GENERATOR" CONTENT="StarOffice 6.0 (Win32)">
+ <META NAME="CREATED" CONTENT="20010710;11455400">
+ <META NAME="CHANGED" CONTENT="20010802;10173004">
+ <STYLE>
+ <!--
+ @page { margin: 2cm }
+ H3 { margin-bottom: 0.21cm }
+ H2 { margin-bottom: 0.21cm; page-break-before: auto; page-break-after: auto }
+ P { margin-bottom: 0.21cm; text-align: left; widows: 2; orphans: 2; page-break-before: auto; page-break-after: auto }
+ H1 { margin-bottom: 0.21cm }
+ P { margin-bottom: 0.21cm; text-align: left; widows: 2; orphans: 2; page-break-before: auto; page-break-after: auto }
+ -->
+ </STYLE>
+</head>
+<body>
+<H1>How To Generate Profiling Data</H1>
+<P>Andre Fischer and Carsten Driesner, July 11<SUP>th</SUP> , 2001.
+Last change on August 2<SUP>nd</SUP> , 2001.</P>
+<H2>Introduction</H2>
+<P>The task that is to be solved is the generation of profiling data
+for a manually selected set of points in programs of the
+OpenOffice/Sun One Webtop family. Moreover this should be
+accomplished as automatically as possible, so that timings of
+different program versions can be compared to each other
+automatically.</P>
+<P>The main reason for not using an existing tool like Truetime or
+Quantify is the huge amount of data generated by these programs. In
+general the developers of the different modules of the office know
+about the time critical parts of their code. Therefore only profiling
+informations about these code parts are of interest. Everything else
+only obscures the view to the relevant data.</P>
+<P>With this in mind we use a different approach. Instead of blindly
+instrumenting---i.e. adding code that generates profiling data---all
+files, we concentrate of the areas of interest. The developers have
+to add once manually commands into their code that emits time stamps
+together with context information. From then on everything else goes
+automatically. If the those files are compiled with a certain
+preprocessor symbol defined and the office is run with a certain
+environment variable set, then profiling information is written to a
+log file (or, to be more precise, to one log file per process). These
+log files are then processed by a Perl script and are transfomed into
+a Calc document.</P>
+<P>The details of this process are explained below. Note that this is
+a work in progress. Especially the transformation of the log files
+into a Calc document will have to be adapted to the needs of those
+who use those documents.</P>
+<H2>Instrumenting the source files</H2>
+<P>The header file <rtl/logfile.hxx> (guarded by the
+preprocessor symbol <CODE>_RTL_LOGFILE_HXX_</CODE>) contains a set of
+macros that can be used to emit time stamps at certain points in the
+code. The reason for using macros instead of a more decent C++
+construct is to provide a way of removing the code for writing
+profiling data completely from the compiled executable and it's
+libraries. The macros wrap calls to the class ::rtl::Logfile
+(declared in <rtl/logfile.hxx>) and the function
+rtl_logfile_trace (declared in <rtl/logfile.h>). They generate
+actual code only when at compile time the preprocessor symbol TIMELOG
+is defined. This is either accomplished by building a special office
+version (which will be the normal Pro-version) or by setting an
+environment variable <CODE>ENVCDEFS</CODE> to include <CODE>-DTIMELOG</CODE>.
+Depending on the shell you use</P>
+<P><CODE>set ENVCDEFS=-DTIMELOG</CODE></P>
+<P>will do that (4NT).</P>
+<P>The macros can be used in two ways:</P>
+<OL>
+ <LI><P><CODE>RTL_LOGFILE_CONTEXT_AUTHOR(instance,project,author,name)</CODE>
+ creates a context instance that can be referenced by <CODE>instance</CODE>.
+ The three remaining parameters contain the name of the project in
+ which the macro is used, the Sun id of the author beeing responsible
+ for the code in which the macro is used (for example af119097 for
+ one of the authors) and the <CODE>name</CODE> of the function or
+ other scope that this context refers to. The context instance emits
+ one time stamp when it is created and one when it is destroyed.
+ Therefore, if placed as first statement of a function definition, a
+ time stamp is written to the log file when the function is entered
+ and one when it is exited even when there is more then one
+ (implicit) return statement.
+ </P>
+ <P>The name passed to the context instantiation is written with
+ every time stamp that originates from such a context. This is also
+ true for the following macros.</P>
+ <LI><P><CODE>RTL_LOGFILE_CONTEXT_TRACE(instance,message)</CODE>,</P>
+ <P><CODE>RTL_LOGFILE_CONTEXT_TRACE1(instance,message,arg1)</CODE>,</P>
+ <P><CODE>RTL_LOGFILE_CONTEXT_TRACE2(instance,message,arg1,arg2)</CODE>,
+ and</P>
+ <P><CODE>RTL_LOGFILE_CONTEXT_TRACE3(instance,message,arg1,arg2,arg3)</CODE>
+ write time stamps with arbitrary messages to the log file. The
+ actual message is given by the string <CODE>message</CODE>. Together
+ with zero to three arguments it is passed to a printf style output
+ function. That means that for every argument there has to be a
+ suitable % format string in <CODE>message</CODE>. In order to allow
+ the log file be parsed by the existing Perl scripts message may
+ contain newlines. Each message is prefixed with the context name.</P>
+ <P>These macros exist also in a context free version.</P>
+ <P><CODE>RTL_LOGFILE_TRACE_AUTHOR(project,author,message)</CODE>,</P>
+ <P><CODE>RTL_LOGFILE_TRACE_AUTHOR1(project,author,message,arg1)</CODE>,</P>
+ <P><CODE>RTL_LOGFILE_TRACE_AUTHOR2(project,author,message,arg1,arg2)</CODE>,
+ and</P>
+ <P><CODE>RTL_LOGFILE_TRACE_AUTHOR3(project,author,message,arg1,arg2,arg3)</CODE>
+ do the same thing as their context twins except that the messages
+ are not prefixed with a context name. As you can see, the project
+ and author have to given to each trace macro instead of just to the
+ one creating a context. They are defined in <rtl/logfile.h>
+ which is included from <rtl/logfile.hxx>. Therefore for only
+ using the context free macros it is sufficient to include
+ <rtl/logfile.h>.</P>
+</OL>
+<P>For every introduced above there is an analogon without the
+<CODE>_AUTHOR</CODE> suffix which do not accept the <CODE>project</CODE>
+and <CODE>author</CODE> arguments. Because both of these are used
+later in the post processing stage we discourage you to use these
+other macro versions.</P>
+<P>Depending on which of these two ways is used to generate a time
+stamp, they are named function/scope time stamps respectively message
+time stamps.</P>
+<H2>Creating profiling information</H2>
+<P>If you have instrumented your code like described above and have
+compiled and installed it you can create profiling information by
+starting the office with the bootsrap variable <CODE>RTL_LOGFILE</CODE>
+set to a file name prefix. This prefix is completed by appending an
+underscore, the process id and a “.log” suffix. Note that
+backslashes have to be escaped by another backslash. The variable
+<CODE>RTL_LOGFILE</CODE> can be set in one of the following ways:</P>
+<UL>
+ <LI><P>Setting the environment variable <CODE>RTL_LOGFILE</CODE>.
+ This for instance be done with</P>
+ <UL>
+ <P><CODE>set RTL_LOG<CODE>FILE</CODE>=c:\\logfile</CODE></P>
+ </UL>
+ <P>from a 4NT shell.</P>
+ <LI><P>Passing the argument <CODE>-env:RTL_LOGFIL<CODE>E=</CODE>c:\\logfile</CODE>
+ on the commandline to the office.</P>
+ <LI><P>Put an entry into <executable><CODE>.ini</CODE> or
+ <executable><CODE>rc</CODE> file (the first with, the second
+ without a dot) where <executable> is the name of the
+ executable. For more information on this method please refer to
+ <A HREF="http://udk.openoffice.org/common/man/concept/uno_default_bootstrapping.html">http://udk.openoffice.org/common/man/concept/uno_default_bootstrapping.html</A></P>
+</UL>
+<H2>Transforming the log files into Calc documents</H2>
+<P>Once you have created a log file you may want to convert it into a
+more readable form. There is a set of Perl scripts that create a Calc
+document from a log file that contains for every thread a set of
+pages with different views of the profiling data.
+</P>
+<P>The first page shows a pretty printed version of the list of time
+stamps. They are indented according to the calling hierarchy. For
+each time stamp you can see the time it has been written (or to be
+more precise the time on which it's writing has been requested), if
+applicable the time the function/scope took to compute and the
+function/scope name and message.</P>
+<P>The second page shows a list of all functions/scopes for which
+timing informations exist. Every list entry shows the function/scope
+name, total, minimal, maximal, and average time and the number of
+calls.</P>
+<H3>Filtering</H3>
+<P>The list of time stamps can be filtered in order to reduce a large
+amount of data to a managable size and to exclude profiling
+information from projects you are not interested in. There are two
+filters. One is for explicit inclusion of time stamps, the other for
+explicit exclusion. Each is initialized from a file containing
+regular expressions (Perl style) given on the command line. The file
+after the <CODE>-i</CODE> switch defines those time stamps that are
+to be included in the reports and the file after the <CODE>-e</CODE>
+switch defines those time stamps that are to be excluded. The files
+may contain empty lines or comment lines whose first character is an
+'#'. An empty inclusion filter does have no effect. If both filters
+are specified, then a time stamp is written to the report if it
+matches at least one of the regular expression of the inclusion
+filter and none of the exclusion filter.</P>
+<P>The idea is to use the inclusion filter if you have just a small
+number of functions or messages you are interested in and to use the
+exclusion filter if there is only a small number you would not like
+in your reports.</P>
+<P>An inclusion file might look like this.</P>
+<P><CODE># Regular expression matching all function names that shall
+show up</CODE></P>
+<P><CODE># in the reports. </CODE>
+</P>
+<P><CODE># Show calls to BuildChart in the chart project.</CODE></P>
+<P><CODE>BuildChart</CODE></P>
+<H3>Outlook</H3>
+<P>The form and number of reports will of course have to be changed
+and extended. We are looking forward to your feedback.</P>
+<H2>Further Documentation</H2>
+<P>Furthor documentation can be found in the C++ header files
+<CODE><rtl/logfile.h></CODE> and <CODE><rtl/logfile.hxx></CODE>
+and the Perl scripts in project <CODE>tools/contrib/profiling</CODE>.
+You can use for instance <CODE>pod2html</CODE> to extract and
+transform the Perl scripts documentation in HTML documents.</P>
+<P>Documentation of the time stamp format can be found <A HREF="time-stamp-format.html">here</A>.</P>
+<H2>Contact</H2>
+<P>You can contact the authors under <A HREF="mailto:andre.w.fischer@sun.com">andre.w.fischer@sun.com</A>
+or <A HREF="mailto:carsten.driesner@sun.com">carsten.driesner@sun.com</A>.</P>
+<P><BR><BR>
+</P>
+</body>
+</HTML>
Propchange: incubator/ooo/ooo-site/trunk/content/tools/profiling/profiling-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/ooo/ooo-site/trunk/content/tools/profiling/profiling-howto.sxw
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/profiling/profiling-howto.sxw?rev=1229624&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/ooo/ooo-site/trunk/content/tools/profiling/profiling-howto.sxw
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation.html?rev=1229624&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation.html (added)
+++ incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation.html Tue Jan 10 16:18:19 2012
@@ -0,0 +1,162 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<head>
+ <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
+ <TITLE></TITLE>
+ <META NAME="GENERATOR" CONTENT="StarOffice 6.0 (Win32)">
+ <META NAME="CREATED" CONTENT="20010724;11274300">
+ <META NAME="CHANGED" CONTENT="20010731;15435171">
+ <STYLE>
+ <!--
+ @page { margin: 2cm }
+ H2 { margin-bottom: 0.21cm; font-family: "Arial", sans-serif; font-size: 14pt; font-style: italic }
+ P { margin-bottom: 0.21cm; text-align: justify; page-break-before: auto; page-break-after: auto }
+ H1 { margin-bottom: 0.21cm; font-family: "Arial", sans-serif; font-size: 16pt }
+ P { margin-bottom: 0.21cm; text-align: justify; page-break-before: auto; page-break-after: auto }
+ -->
+ </STYLE>
+</head>
+<body>
+<H1>Profiling: Time Stamp Documentation</H1>
+<P>The purpose of this document is to give those of us who write
+filters for post-processing and analysis of profiling log files an
+overview over the available time stamps and their meaning. The
+documentation should enable us to write a filter which extracts only
+those time stamps from a log file that belong to a specific task say
+for example the loading of a writer document in XML format.</P>
+<P>Don't include a description of every time stamp into this
+document.</P>
+<H2>Format</H2>
+<P>The description of a time <SPAN STYLE="font-style: normal">stamp
+should include the following information:</SPAN></P>
+<OL>
+ <LI><P STYLE="font-style: normal">A (very) short description that
+ serves as a title.</P>
+ <LI><P STYLE="font-style: normal">The line that is written to the
+ logfile (that part of it that follows time and threadid of course).
+ Be very carefull with this because it is used in regular expressions
+ to match the time stamps in the log files. In time stamps that are
+ emitted on entering and leaving a function or other scope replace
+ the opening or closing curly brackets by a set of both (and include
+ such time stamps only once).</P>
+ <LI><P STYLE="font-style: normal">A description that tells the
+ filter writer what happens in the function that is bracketed with
+ the time stamp(s) in question, resp. what a message time stamp tells
+ you.</P>
+ <LI><P STYLE="font-style: normal">Whatever information you think
+ would be helpfull to the filter writer.</P>
+</OL>
+<H2>Example</H2>
+<P>Look at the following table taken from the chart project for an
+example of what time stamp descriptions might look like. Here <SAMP>sch</SAMP>
+is the name of the project (chart) and af is the author short</P>
+<TABLE COLS=4 WIDTH=100% BORDER=1 CELLPADDING=2 CELLSPACING=0 FRAME=BELOW RULES=GROUPS>
+ <COL WIDTH=95>
+ <COL WIDTH=269>
+ <COL WIDTH=465>
+ <COL WIDTH=521>
+ <Tbody>
+ <TR VALIGN=TOP>
+ <TD WIDTH=95 HEIGHT=32 BGCOLOR="#ccccff">
+ <P ALIGN=LEFT><FONT SIZE=3><B>Project</B></FONT></P>
+ </TD>
+ <TD WIDTH=269 BGCOLOR="#ccccff">
+ <P ALIGN=LEFT><FONT SIZE=3><B>Short description</B></FONT></P>
+ </TD>
+ <TD WIDTH=465 BGCOLOR="#ccccff">
+ <P ALIGN=LEFT><FONT SIZE=3><B>Time stamp</B></FONT></P>
+ </TD>
+ <TD WIDTH=521 BGCOLOR="#ccccff">
+ <P ALIGN=LEFT><FONT SIZE=3><B>Description</B></FONT></P>
+ </TD>
+ </TR>
+ </Tbody>
+ <Tbody>
+ <TR>
+ <TD WIDTH=95 HEIGHT=40 VALIGN=TOP>
+ <P ALIGN=LEFT>Sch (Chart)</P>
+ </TD>
+ <TD WIDTH=269 VALIGN=TOP>
+ <P ALIGN=LEFT>Main function of the chart.</P>
+ </TD>
+ <TD WIDTH=465 VALIGN=TOP>
+ <P ALIGN=LEFT>{} sch (af119097) ::ChartModel::BuildChart</P>
+ </TD>
+ <TD WIDTH=521>
+ <P ALIGN=LEFT>BuildChart is the method that does most of the work
+ in creating a chart and consumes most of the time. It is called
+ mutch to often.</P>
+ </TD>
+ </TR>
+ <TR>
+ <TD WIDTH=95 HEIGHT=40 VALIGN=TOP>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=269 VALIGN=TOP>
+ <P ALIGN=LEFT>Build chart not skipped</P>
+ </TD>
+ <TD WIDTH=465 VALIGN=TOP>
+ <P ALIGN=LEFT>{} sch (af119097) ::ChartModel::BuildChart : {}
+ full</P>
+ </TD>
+ <TD WIDTH=521>
+ <P ALIGN=LEFT>Indication that due to a lock of the model the
+ build chart has not been skipped.</P>
+ </TD>
+ </TR>
+ </Tbody>
+ <Tbody>
+ <TR>
+ <TD WIDTH=95 HEIGHT=22 VALIGN=TOP>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=269 VALIGN=TOP>
+ <P ALIGN=LEFT>Loading of a chart</P>
+ </TD>
+ <TD WIDTH=465 VALIGN=TOP>
+ <P ALIGN=LEFT>{} sch (af119097) ::SchChartDocShell::Load</P>
+ </TD>
+ <TD WIDTH=521>
+ <P ALIGN=LEFT>Loading of a chart object.</P>
+ </TD>
+ </TR>
+ <TR>
+ <TD WIDTH=95 HEIGHT=20 VALIGN=TOP>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=269 VALIGN=TOP>
+ <P ALIGN=LEFT>Chart is loaded from XML format</P>
+ </TD>
+ <TD WIDTH=465 VALIGN=TOP>
+ <P ALIGN=LEFT>| sch (af119097) ::SchChartDocShell::Load : XML
+ Format</P>
+ </TD>
+ <TD WIDTH=521>
+ <P ALIGN=LEFT>Chart is loaded from an XML storage.</P>
+ </TD>
+ </TR>
+ <TR>
+ <TD WIDTH=95 HEIGHT=22 VALIGN=TOP>
+ <P><BR>
+ </P>
+ </TD>
+ <TD WIDTH=269 VALIGN=TOP>
+ <P ALIGN=LEFT>Chart is loaded from binary format</P>
+ </TD>
+ <TD WIDTH=465 VALIGN=TOP>
+ <P ALIGN=LEFT>| sch (af119097) ::SchChartDocShell::Load : Binary
+ Format</P>
+ </TD>
+ <TD WIDTH=521>
+ <P ALIGN=LEFT>Chart is loaded from a binary storage.</P>
+ </TD>
+ </TR>
+ </Tbody>
+</TABLE>
+<P><BR><BR>
+</P>
+</body>
+</HTML>
Propchange: incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation.sxc
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation.sxc?rev=1229624&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation.sxc
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation_html_m788e0595.gif
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation_html_m788e0595.gif?rev=1229624&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-documentation_html_m788e0595.gif
------------------------------------------------------------------------------
svn:mime-type = image/gif
Added: incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-format.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-format.html?rev=1229624&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-format.html (added)
+++ incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-format.html Tue Jan 10 16:18:19 2012
@@ -0,0 +1,165 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<head>
+ <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
+ <TITLE></TITLE>
+ <META NAME="GENERATOR" CONTENT="StarOffice 6.0 (Win32)">
+ <META NAME="CREATED" CONTENT="20010719;12323000">
+ <META NAME="CHANGED" CONTENT="20010802;10214237">
+ <STYLE>
+ <!--
+ @page { margin: 2cm }
+ H2 { margin-bottom: 0.21cm; font-style: normal; text-align: justify }
+ P { margin-bottom: 0.21cm; text-align: left; page-break-before: auto; page-break-after: auto }
+ H1 { margin-bottom: 0.21cm; text-align: justify }
+ P { margin-bottom: 0.21cm; text-align: left; page-break-before: auto; page-break-after: auto }
+ CODE { font-size: 12pt }
+ SAMP { font-size: 9pt }
+ -->
+ </STYLE>
+</head>
+<body>
+<H1 STYLE="text-indent: 1.38cm">How to format profiling time stamp
+messages</H1>
+<P>Carsten Driesner and Andre Fischer, last change on August 2<SUP>nd</SUP>,
+2001</P>
+<H2>Introduction</H2>
+<P>Each use of the macros <CODE>RTL_LOGFILE_CONTEXT_AUTHOR,
+RTL_LOGFILE_CONTEXT_TRACE</CODE><EM><n></EM><CODE>,</CODE> and<CODE>
+RTL_LOGFILE_TRACE_AUTHOR</CODE><EM><n></EM> writes a time stamp
+into a logfile that can be parsed by post-processing scripts. This
+works only if the text that is given as arguments to the macros
+follows certain rules.</P>
+<P>The next section describes the overall format of the time stamps
+written by the macros. The format of the text passed as arguments to
+the macros is described int the third section.</P>
+<H2>Overall time stamp format</H2>
+<P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+Each time stamp written by one of the macros
+<CODE>RTL_LOGFILE_CONTEXT_AUTHOR, RTL_LOGFILE_CONTEXT_TRACE</CODE><EM><n></EM><CODE>,</CODE>
+and <CODE>RTL_LOGFILE_TRACE_AUTHOR</CODE><EM><n></EM> has the
+format</P>
+<P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+%d %d %c %s : %s</P>
+<P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+with the following arguments:</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+ Time in milliseconds after the first time stamp. This implies that
+ the first time stamp has always a value of 0 in this field. To
+ convert the relative times into absolute ones or ones that are
+ relative to the application start you can evaluate the first line in
+ the log-file which is described below.</P>
+ <LI><P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+ Id of the thread from which the time stamp has been emitted. The
+ process id can be determined from the name of the log-file.</P>
+ <LI><P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+ A character the classifies the time steps into three classes:</P>
+</OL>
+<OL>
+ <LI><P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+ An { indicates the beginning of a function or other scope.</P>
+ <LI><P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+ An } indicates the end of a function or other scope.</P>
+ <LI><P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+ An | indicates a message from within a scope or without a scope.</P>
+</OL>
+<OL START=4>
+ <LI><P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+ Name or description of a function or other scope. This name is used
+ to group beginnings and ends of a scope together. If
+ <CODE>RTL_LOGFILE_TRACE_AUTHOR</CODE><EM><n></EM> is used
+ instead of <CODE>RTL_LOGFILE_CONTEXT_TRACE</CODE><EM><n></EM>
+ then this field remains empty.</P>
+ <LI><P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+ Arbitrary message written by <CODE>RTL_LOGFILE_TRACE_AUTHOR</CODE><EM><n></EM>
+ and <CODE>RTL_LOGFILE_CONTEXT_TRACE</CODE><EM><n></EM>. If
+ <CODE>RTL_LOGFILE_CONTEXT_AUTHOR</CODE> is used instead then this
+ field remains empty.</P>
+</OL>
+<P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+Note that the dividing colon between the last two fields is written
+even if one of them remains empty.</P>
+<P STYLE="margin-bottom: 0cm; page-break-before: auto; page-break-after: auto">
+As you can see, you can only specify the content of the last two
+fields. The format that they may have is described in the following
+section.</P>
+<H2>Admissable format of scope names and messages</H2>
+<P>This section focuses on the format of the last two fields of a
+time stamp. The first one should have format</P>
+<P>%s (%s) %s
+</P>
+<P>with the following arguments:</P>
+<OL>
+ <LI><P>Module name. This will be strings like <CODE>sfx2</CODE> or
+ <CODE>desktop</CODE>.</P>
+ <LI><P>Sun id with prefixed shortcut of responsible developer. That
+ would be <CODE>cd100003</CODE> or <CODE>af119097</CODE> for the
+ authors. Use the Sun id of the project owner, if you have no Sun id<I>.</I></P>
+ <LI><P>Fully qualified function name with leading double colon. Add
+ a simplified signature only if that is necessary to distinguish it
+ from other functions with the same name. The function name starts
+ with the complete namespace, the class name (if it is really a
+ method) and finally the actual function name.</P>
+</OL>
+<P>The three fields are separated by singles spaces.</P>
+<P>The second argument may have any format you like with two
+constraints:</P>
+<OL>
+ <LI><P>It may not contain a newline character.</P>
+ <LI><P>If it starts with an opening or a closing curly bracket then
+ it has a meaning similar to the third field of the overall format:
+ it describes the beginning or end of a scope. You can define a
+ logical scope with this format even though you don't have an analog
+ physical representation and don't want to introduce a new scope for
+ it.</P>
+</OL>
+<P>Use RTL_LOGFILE_CONTEXT_AUTHOR<n> if possible to
+automatically write the fields described above with every time stamp
+emitted from the context. If that is not possible or usefull then
+start the message field with a string that has the format described
+above. Use your common sense to fill in the second and fourth field.
+Divide that string with a colon surrounded by spaces from the actual
+message string.</P>
+<H2>Examples</H2>
+<P>The following pseudo code uses a context to write time stamps at
+the beginning and end of scopes in the implicit form and the explicit
+one that uses the message string to indicate the scope boundaries.</P>
+<P><SAMP>void ::Desktop::OpenStartupscreen (arguments)</SAMP></P>
+<P><SAMP>{</SAMP></P>
+<P><SAMP>RTL_LOGFILE_CONTEXT_AUTHOR (aInstance, „desktop“,
+„cd100003“, „::Desktop::OpenStartupscreen“);</SAMP></P>
+<P><SAMP>...</SAMP></P>
+<P><SAMP>RTL_LOGFILE_CONTEXT_TRACE (aInstance, „{ lengthy
+calculation“);</SAMP></P>
+<P><SAMP>for (...)</SAMP></P>
+<P><SAMP>{</SAMP></P>
+<P><SAMP>do something</SAMP></P>
+<P><SAMP>}</SAMP></P>
+<P><SAMP>RTL_LOGFILE_CONTEXT_TRACE (aInstance, „} lengthy
+calculation“);</SAMP></P>
+<P><CODE>}</CODE></P>
+<P>It generate time stamps like these:</P>
+<P><SAMP>001234 11 { desktop (cd100003) ::Desktop::OpenStartupscreen</SAMP></P>
+<P><SAMP>002345 11 | desktop (cd<SAMP>100003</SAMP>)
+::Desktop::OpenStartupscreen : { lengthy calculation</SAMP></P>
+<P><SAMP>003456 11 | desktop (cd<SAMP>100003</SAMP>)
+::Desktop::OpenStartupscreen : } lengthy calculation</SAMP></P>
+<P><SAMP>004567 11 } desktop (cd<SAMP>100003</SAMP>)
+::Desktop::OpenStartupscreen</SAMP></P>
+<P><BR><BR>
+</P>
+<P>This pseudo code uses the context free version:</P>
+<P><SAMP>void ::Desktop::CloseStartupscreen</SAMP></P>
+<P><SAMP>{</SAMP></P>
+<P><SAMP>...</SAMP></P>
+<P><SAMP>RTL_LOGFILE_TRACE_AUTHOR („desktop“, „cd<SAMP>100003“,
+„:</SAMP>:Desktop::CloseStartupscreen : Startup finished“);</SAMP></P>
+<P><SAMP>}</SAMP></P>
+<P>It's output might look like this:</P>
+<P><SAMP>099999 11 | desktop (cd<SAMP>100003</SAMP>)
+::Desktop::CloseStartupscreen : Startup finished</SAMP></P>
+<P><BR><BR>
+</P>
+</body>
+</HTML>
Propchange: incubator/ooo/ooo-site/trunk/content/tools/profiling/time-stamp-format.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: incubator/ooo/ooo-site/trunk/content/tools/profiling/write-calc-doc.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/profiling/write-calc-doc.html?rev=1229624&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/tools/profiling/write-calc-doc.html (added)
+++ incubator/ooo/ooo-site/trunk/content/tools/profiling/write-calc-doc.html Tue Jan 10 16:18:19 2012
@@ -0,0 +1,110 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<head>
+ <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
+ <TITLE></TITLE>
+ <!-- Changed by: Andre Fischer, 14-Sep-2001 -->
+ <META NAME="GENERATOR" CONTENT="StarOffice 6.0 (Win32)">
+ <META NAME="AUTHOR" CONTENT="Martin Hollmichel">
+ <META NAME="CREATED" CONTENT="20010419;16101287">
+ <META NAME="CHANGED" CONTENT="20010802;14455412">
+ <STYLE>
+ <!--
+ SAMP { font-size: 10pt }
+ -->
+ </STYLE>
+</head>
+<body>
+<H2>write-calc-doc.pl</H2>
+<P>The Perl script write-calc-doc.pl transforms a log file into a
+Calc document containing two data sheets for every thread. The first
+sheet displays a pretty printed version of the raw data. The second
+sheet is made up by a table that contains for each function or other
+scope the minimal, maximal, average, and total time and the number of
+calls.</P>
+<H3>Synopsis</H3>
+<P>write-calc-doc.pl <log-file-name> [<calc-document-name>]</P>
+<P>The two arguments specify the name of the log-file to process and
+an optional name under which to write the report. If that name is
+not given explicetly, then it is derived from the log-file name by
+replacing the suffix <CODE>.log</CODE> by the suffix <CODE>.sxc</CODE>.</P>
+<P>write-calc-doc.pl understands the following option parameters that
+may stand anywhere on the command line (but of course behind the
+script name):</P>
+<UL>
+ <LI><P>-h prints a short help text describing the command line
+ parameters.</P>
+ <LI><P>-i <filename> specifies a file that contains regular
+ expressions (in Perl style). Every time stamp in the log file that
+ matches at least one of these expressions is included into the
+ report.</P>
+ <LI><P>-e <filename> specifies a file that contains regular
+ expressions (in Perl style). Every time stamp in the log file that
+ matches at least one of these expressions is <B>not</B> included
+ into the report.</P>
+</UL>
+<H3>Configuration</H3>
+<P>There are several configuration features which the script tries to
+determine automatically. If that fails you have to specify them
+explicitly:</P>
+<UL>
+ <LI><P>If the perl interpreter is not found you have to specify it
+ on the command line: use <SAMP><perl-path>/perl
+ write-calc-doc.pl <arguments></SAMP> instead of
+ <SAMP>write-calc-doc.pl <arguments></SAMP>.</P>
+ <LI><P>The Perl script uses several modules in the sub-directory
+ LogFile. If that sub-directory is not in your Perl search path and
+ can't be deduced automatically from the script's own name then you
+ have to pass that directory with the -I command line option to the
+ perl interpreter: use <SAMP><perl-path>/perl
+ -I<src-path>/tools/contrib/profiling write-calc-doc.pl
+ <arguments>.</SAMP></P>
+ <LI><P>A zip executable is used to pack all XML files into a single
+ archive. If no zip executable with the base name „zip“ is
+ found in the current search path, then you have to set the
+ environment variables LOG_FILE_ZIP_COMMAND to the path name of the
+ zip executable. The variable LOG_FILE_ZIP_FLAGS can be used to
+ control it's behaviour.</P>
+</UL>
+<P>Usually it should be sufficient to say</P>
+<P><SAMP><src-path>/tools/contrib/profiling/write-calc-document.pl
+/tmp/profiling_1234.log</SAMP></P>
+<P>It creates the Calc document <CODE>/tmp/profiling_1234.sxc</CODE>.</P>
+<H3>Filtering the log file</H3>
+<P>On the command line you can specify two files with regular
+expressions. These expressions are used to filter the time stamps in
+the log file. A time stamp is taken into account for the report
+generation if it a) matches at least one regular expression in the
+inclusion filter file or that file is empty and b) matches none of
+the regular expressions in the exclusion filter file or that file is
+empty. The expressions in the filter files have to be written in the
+Perl <SPAN STYLE="font-style: normal">syntax.</SPAN></P>
+<H4>Filter Examples</H4>
+<P>An inclusion filter file containing only the line</P>
+<P><CODE>\(af119097\)</CODE></P>
+<P>includes exactly those time stamps into the report that belong the
+author with Sun id af119097.</P>
+<P>An exclusion filter file containing only the line</P>
+<P><CODE>^sch\b</CODE></P>
+<P>removes all time stamps from the report that belong to the chart
+project.</P>
+<h3>Further documentation</h3>
+Follow the links below to the documentation contained in the
+Perl scripts write-calc-document.pl and the modules loaded by it. It has been created by running
+pod2html on the script files.
+<ul>
+<li><a href="pod/write-calc-doc.html">write-calc-doc.pl</a></li>
+<li><a href="pod/LogFile/Filter.html">LogFile/Filter.pm</a></li>
+<li><a href="pod/LogFile/Parser.html">LogFile/Parser.pm</a></li>
+<li><a href="pod/LogFile/Processor.html">LogFile/Processor.pm</a></li>
+<li><a href="pod/LogFile/XML.html">LogFile/XML.pm</a></li>
+</ul>
+<H3>References</H3>
+<P>For writing filters suitable for a given task you should have a
+look at the <A HREF="time-stamp-format.html">specification</A> of the
+general time stamp format and the <A HREF="time-stamp-documentation.html">documentation</A>
+of the time stamps emitted from the individual projects.</P>
+<P><BR><BR>
+</P>
+</body>
+</HTML>
Propchange: incubator/ooo/ooo-site/trunk/content/tools/profiling/write-calc-doc.html
------------------------------------------------------------------------------
svn:eol-style = native