diff --git a/manual/tracy.tex b/manual/tracy.tex index 6acc448a..1da24b55 100644 --- a/manual/tracy.tex +++ b/manual/tracy.tex @@ -104,6 +104,7 @@ Hello and welcome to the Tracy Profiler user manual! Here you will find all the \item Chapter~\ref{client}, \emph{\nameref{client}}, provides information on how to instrument your application, in order to retrieve useful profiling data. \item Chapter~\ref{capturing}, \emph{\nameref{capturing}}, goes into more detail on how the profiling information can be captured and stored on disk. \item Chapter~\ref{analyzingdata}, \emph{\nameref{analyzingdata}}, guides you through the graphical user interface of the profiler. +\item Chapter~\ref{csvexport}, \emph{\nameref{csvexport}}, explains how to export some zone timing statistics into a CSV format. \item Chapter~\ref{importingdata}, \emph{\nameref{importingdata}}, documents how to import data from other profilers. \item Chapter~\ref{configurationfiles}, \emph{\nameref{configurationfiles}}, gives information on the profiler settings. \end{itemize} @@ -3017,6 +3018,37 @@ This window lists all annotations marked on the timeline. Each annotation is pre \label{figannlist} \end{figure} +\section{Exporting zone statistics to CSV} +\label{csvexport} + +You can use a command-line utility in the \texttt{csvexport} directory to export basic zone statistics from a saved trace into a CSV format. +The tool requires a single .tracy file as an argument and prints results into the standard output (stdout) from where you can redirect it into a file or use it as an input into another tool. +By default, the utility will list all zones with the following columns: + +\begin{itemize} + \item \texttt{name} -- Zone name + \item \texttt{src\_file} -- Source file where the zone was set + \item \texttt{src\_line} -- Line in the source file where the zone was set + \item \texttt{total\_ns} -- Total zone time in nanoseconds + \item \texttt{total\_perc} -- Total zone time as a percentage of the program's execution time + \item \texttt{counts} -- Zone count + \item \texttt{mean\_ns} -- Mean zone time (equivalent in MPTC in the profiler GUI) in nanoseconds + \item \texttt{min\_ns} -- Minimum zone time in nanoseconds + \item \texttt{max\_ns} -- Maximum zone time in nanoseconds + \item \texttt{std\_ns} -- Standard deviation of the zone time in nanoseconds +\end{itemize} + +You can customize the output with the following command line options: + +\begin{itemize} + \item \texttt{-h, -\hspace{-1.25ex} -help} -- display a help message + \item \texttt{-f, -\hspace{-1.25ex} -filter } -- filter the zone names + \item \texttt{-c, -\hspace{-1.25ex} -case} -- make the name filtering case sensitive + \item \texttt{-s, -\hspace{-1.25ex} -sep } -- customize the CSV separator (default is ``\texttt{,}'') + \item \texttt{-e, -\hspace{-1.25ex} -self} -- use self time (equivalent to the ``Self time'' toggle in the profiler GUI) + \item \texttt{-u, -\hspace{-1.25ex} -unwrap} -- report each zone individually; this will discard the statistics columns and instead reports for each zone entry its timestamp and the duration of the zone entry. +\end{itemize} + \section{Importing external profiling data} \label{importingdata}