Autogenerated HTML docs for v2.38.1-385-g3b088

2 files changed, 286 insertions, 117 deletions

diff --git a/technical/api-trace2.html b/technical/api-trace2.html
index b04dcc5eb..e0ceee971 100644
--- a/technical/api-trace2.html
+++ b/technical/api-trace2.html
@@ -909,69 +909,23 @@ filename collisions).</p></div>
 <div class="sect1">

 <h2 id="_trace2_api">Trace2 API</h2>

 <div class="sectionbody">

-<div class="paragraph"><p>All public Trace2 functions and macros are defined in <code>trace2.h</code> and

-<code>trace2.c</code>.  All public symbols are prefixed with <code>trace2_</code>.</p></div>

+<div class="paragraph"><p>The Trace2 public API is defined and documented in <code>trace2.h</code>; refer to it for

+more information.  All public functions and macros are prefixed

+with <code>trace2_</code> and are implemented in <code>trace2.c</code>.</p></div>

 <div class="paragraph"><p>There are no public Trace2 data structures.</p></div>

 <div class="paragraph"><p>The Trace2 code also defines a set of private functions and data types

 in the <code>trace2/</code> directory.  These symbols are prefixed with <code>tr2_</code>

-and should only be used by functions in <code>trace2.c</code>.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_conventions_for_public_functions_and_macros">Conventions for Public Functions and Macros</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>The functions defined by the Trace2 API are declared and documented

-in <code>trace2.h</code>.  It defines the API functions and wrapper macros for

-Trace2.</p></div>

+and should only be used by functions in <code>trace2.c</code> (or other private

+source files in <code>trace2/</code>).</p></div>

+<div class="sect2">

+<h3 id="_conventions_for_public_functions_and_macros">Conventions for Public Functions and Macros</h3>

 <div class="paragraph"><p>Some functions have a <code>_fl()</code> suffix to indicate that they take <code>file</code>

 and <code>line-number</code> arguments.</p></div>

 <div class="paragraph"><p>Some functions have a <code>_va_fl()</code> suffix to indicate that they also

 take a <code>va_list</code> argument.</p></div>

 <div class="paragraph"><p>Some functions have a <code>_printf_fl()</code> suffix to indicate that they also

 take a <code>printf()</code> style format with a variable number of arguments.</p></div>

-<div class="paragraph"><p>There are CPP wrapper macros and <code>#ifdef`s to hide most of these details.

-See `trace2.h</code> for more details.  The following discussion will only

-describe the simplified forms.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_public_api">Public API</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>All Trace2 API functions send a message to all of the active

-Trace2 Targets.  This section describes the set of available

-messages.</p></div>

-<div class="paragraph"><p>It helps to divide these functions into groups for discussion

-purposes.</p></div>

-<div class="sect2">

-<h3 id="_basic_command_messages">Basic Command Messages</h3>

-<div class="paragraph"><p>These are concerned with the lifetime of the overall git process.

-e.g: <code>void trace2_initialize_clock()</code>, <code>void trace2_initialize()</code>,

-<code>int trace2_is_enabled()</code>, <code>void trace2_cmd_start(int argc, const char **argv)</code>.</p></div>

-</div>

-<div class="sect2">

-<h3 id="_command_detail_messages">Command Detail Messages</h3>

-<div class="paragraph"><p>These are concerned with describing the specific Git command

-after the command line, config, and environment are inspected.

-e.g: <code>void trace2_cmd_name(const char *name)</code>,

-<code>void trace2_cmd_mode(const char *mode)</code>.</p></div>

-</div>

-<div class="sect2">

-<h3 id="_child_process_messages">Child Process Messages</h3>

-<div class="paragraph"><p>These are concerned with the various spawned child processes,

-including shell scripts, git commands, editors, pagers, and hooks.</p></div>

-<div class="paragraph"><p>e.g: <code>void trace2_child_start(struct child_process *cmd)</code>.</p></div>

-</div>

-<div class="sect2">

-<h3 id="_git_thread_messages">Git Thread Messages</h3>

-<div class="paragraph"><p>These messages are concerned with Git thread usage.</p></div>

-<div class="paragraph"><p>e.g: <code>void trace2_thread_start(const char *thread_name)</code>.</p></div>

-</div>

-<div class="sect2">

-<h3 id="_region_and_data_messages">Region and Data Messages</h3>

-<div class="paragraph"><p>These are concerned with recording performance data

-over regions or spans of code. e.g:

-<code>void trace2_region_enter(const char *category, const char *label, const struct repository *repo)</code>.</p></div>

-<div class="paragraph"><p>Refer to trace2.h for details about all trace2 functions.</p></div>

+<div class="paragraph"><p>CPP wrapper macros are defined to hide most of these details.</p></div>

 </div>

 </div>

 </div>

@@ -1600,8 +1554,8 @@ not be compared to the child&#8217;s atexit times.</p></div>
 <dd>

 <p>

         This event is generated when a thread is started.  It is

-        generated from <strong>within</strong> the new thread&#8217;s thread-proc (for TLS

-        reasons).

+        generated from <strong>within</strong> the new thread&#8217;s thread-proc (because

+        it needs to access data in the thread&#8217;s thread-local storage).

 </p>

 <div class="listingblock">

 <div class="content">

@@ -1618,7 +1572,7 @@ not be compared to the child&#8217;s atexit times.</p></div>
 <dd>

 <p>

         This event is generated when a thread exits.  It is generated

-        from <strong>within</strong> the thread&#8217;s thread-proc (for TLS reasons).

+        from <strong>within</strong> the thread&#8217;s thread-proc.

 </p>

 <div class="listingblock">

 <div class="content">

@@ -1763,6 +1717,92 @@ filter deeply nested regions and data events.  It defaults to "2".</p></div>
 }</code></pre>

 </div></div>

 </dd>

+<dt class="hdlist1">

+<code>"th_timer"</code>

+</dt>

+<dd>

+<p>

+        This event logs the amount of time that a stopwatch timer was

+        running in the thread.  This event is generated when a thread

+        exits for timers that requested per-thread events.

+</p>

+<div class="listingblock">

+<div class="content">

+<pre><code>{

+        "event":"th_timer",

+        ...

+        "category":"my_category",

+        "name":"my_timer",

+        "intervals":5,         # number of time it was started/stopped

+        "t_total":0.052741,    # total time in seconds it was running

+        "t_min":0.010061,      # shortest interval

+        "t_max":0.011648       # longest interval

+}</code></pre>

+</div></div>

+</dd>

+<dt class="hdlist1">

+<code>"timer"</code>

+</dt>

+<dd>

+<p>

+        This event logs the amount of time that a stopwatch timer was

+        running aggregated across all threads.  This event is generated

+        when the process exits.

+</p>

+<div class="listingblock">

+<div class="content">

+<pre><code>{

+        "event":"timer",

+        ...

+        "category":"my_category",

+        "name":"my_timer",

+        "intervals":5,         # number of time it was started/stopped

+        "t_total":0.052741,    # total time in seconds it was running

+        "t_min":0.010061,      # shortest interval

+        "t_max":0.011648       # longest interval

+}</code></pre>

+</div></div>

+</dd>

+<dt class="hdlist1">

+<code>"th_counter"</code>

+</dt>

+<dd>

+<p>

+        This event logs the value of a counter variable in a thread.

+        This event is generated when a thread exits for counters that

+        requested per-thread events.

+</p>

+<div class="listingblock">

+<div class="content">

+<pre><code>{

+        "event":"th_counter",

+        ...

+        "category":"my_category",

+        "name":"my_counter",

+        "count":23

+}</code></pre>

+</div></div>

+</dd>

+<dt class="hdlist1">

+<code>"counter"</code>

+</dt>

+<dd>

+<p>

+        This event logs the value of a counter variable across all threads.

+        This event is generated when the process exits.  The total value

+        reported here is the sum across all threads.

+</p>

+<div class="listingblock">

+<div class="content">

+<pre><code>{

+        "event":"counter",

+        ...

+        "category":"my_category",

+        "name":"my_counter",

+        "count":23

+}</code></pre>

+</div></div>

+</dd>

 </dl></div>

 </div>

 </div>

@@ -2171,7 +2211,7 @@ the index.  Thread "th01" worked on 508 items at offset 0.  Thread "th02"
 worked on 508 items at offset 2032.  Thread "th04" worked on 508 items

 at offset 508.</p></div>

 <div class="paragraph"><p>This example also shows that thread names are assigned in a racy manner

-as each thread starts and allocates TLS storage.</p></div>

+as each thread starts.</p></div>

 </dd>

 <dt class="hdlist1">

 Config (def param) Events

@@ -2215,6 +2255,61 @@ d0 | main                     | exit         |     |  0.000470 |           |
 d0 | main                     | atexit       |     |  0.000477 |           |              | code:0</code></pre>

 </div></div>

 </dd>

+<dt class="hdlist1">

+Stopwatch Timer Events

+</dt>

+<dd>

+<p>

+        Measure the time spent in a function call or span of code

+        that might be called from many places within the code

+        throughout the life of the process.

+</p>

+<div class="listingblock">

+<div class="content">

+<pre><code>static void expensive_function(void)

+{

+        trace2_timer_start(TRACE2_TIMER_ID_TEST1);

+        ...

+        sleep_millisec(1000); // Do something expensive

+        ...

+        trace2_timer_stop(TRACE2_TIMER_ID_TEST1);

+}

+

+static int ut_100timer(int argc, const char **argv)

+{

+        ...

+

+        expensive_function();

+

+        // Do something else 1...

+

+        expensive_function();

+

+        // Do something else 2...

+

+        expensive_function();

+

+        return 0;

+}</code></pre>

+</div></div>

+<div class="paragraph"><p>In this example, we measure the total time spent in

+<code>expensive_function()</code> regardless of when it is called

+in the overall flow of the program.</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><code>$ export GIT_TRACE2_PERF_BRIEF=1

+$ export GIT_TRACE2_PERF=~/log.perf

+$ t/helper/test-tool trace2 100timer 3 1000

+...

+$ cat ~/log.perf

+d0 | main                     | version      |     |           |           |              | ...

+d0 | main                     | start        |     |  0.001453 |           |              | t/helper/test-tool trace2 100timer 3 1000

+d0 | main                     | cmd_name     |     |           |           |              | trace2 (trace2)

+d0 | main                     | exit         |     |  3.003667 |           |              | code:0

+d0 | main                     | timer        |     |           |           | test         | name:test1 intervals:3 total:3.001686 min:1.000254 max:1.000929

+d0 | main                     | atexit       |     |  3.003796 |           |              | code:0</code></pre>

+</div></div>

+</dd>

 </dl></div>

 </div>

 </div>

@@ -2259,7 +2354,7 @@ Trace2 targets (and convert &lt;key&gt; to a "category").
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2022-08-30 10:56:31 PDT

+ 2022-11-04 21:49:36 PDT

 </div>

 </div>

 </body>

diff --git a/technical/api-trace2.txt b/technical/api-trace2.txt
index 2afa28bb5..de5fc2505 100644
--- a/technical/api-trace2.txt
+++ b/technical/api-trace2.txt
@@ -148,20 +148,18 @@ filename collisions).
 
 == Trace2 API
 
-All public Trace2 functions and macros are defined in `trace2.h` and
-`trace2.c`.  All public symbols are prefixed with `trace2_`.
+The Trace2 public API is defined and documented in `trace2.h`; refer to it for
+more information.  All public functions and macros are prefixed
+with `trace2_` and are implemented in `trace2.c`.
 
 There are no public Trace2 data structures.
 
 The Trace2 code also defines a set of private functions and data types
 in the `trace2/` directory.  These symbols are prefixed with `tr2_`
-and should only be used by functions in `trace2.c`.
+and should only be used by functions in `trace2.c` (or other private
+source files in `trace2/`).
 
-== Conventions for Public Functions and Macros
-
-The functions defined by the Trace2 API are declared and documented
-in `trace2.h`.  It defines the API functions and wrapper macros for
-Trace2.
+=== Conventions for Public Functions and Macros
 
 Some functions have a `_fl()` suffix to indicate that they take `file`
 and `line-number` arguments.
@@ -172,52 +170,7 @@ take a `va_list` argument.
 Some functions have a `_printf_fl()` suffix to indicate that they also
 take a `printf()` style format with a variable number of arguments.
 
-There are CPP wrapper macros and `#ifdef`s to hide most of these details.
-See `trace2.h` for more details.  The following discussion will only
-describe the simplified forms.
-
-== Public API
-
-All Trace2 API functions send a message to all of the active
-Trace2 Targets.  This section describes the set of available
-messages.
-
-It helps to divide these functions into groups for discussion
-purposes.
-
-=== Basic Command Messages
-
-These are concerned with the lifetime of the overall git process.
-e.g: `void trace2_initialize_clock()`, `void trace2_initialize()`,
-`int trace2_is_enabled()`, `void trace2_cmd_start(int argc, const char **argv)`.
-
-=== Command Detail Messages
-
-These are concerned with describing the specific Git command
-after the command line, config, and environment are inspected.
-e.g: `void trace2_cmd_name(const char *name)`,
-`void trace2_cmd_mode(const char *mode)`.
-
-=== Child Process Messages
-
-These are concerned with the various spawned child processes,
-including shell scripts, git commands, editors, pagers, and hooks.
-
-e.g: `void trace2_child_start(struct child_process *cmd)`.
-
-=== Git Thread Messages
-
-These messages are concerned with Git thread usage.
-
-e.g: `void trace2_thread_start(const char *thread_name)`.
-
-=== Region and Data Messages
-
-These are concerned with recording performance data
-over regions or spans of code. e.g:
-`void trace2_region_enter(const char *category, const char *label, const struct repository *repo)`.
-
-Refer to trace2.h for details about all trace2 functions.
+CPP wrapper macros are defined to hide most of these details.
 
 == Trace2 Target Formats
 
@@ -685,8 +638,8 @@ The "exec_id" field is a command-unique id and is only useful if the
 
 `"thread_start"`::
 	This event is generated when a thread is started.  It is
-	generated from *within* the new thread's thread-proc (for TLS
-	reasons).
+	generated from *within* the new thread's thread-proc (because
+	it needs to access data in the thread's thread-local storage).
 +
 ------------
 {
@@ -698,7 +651,7 @@ The "exec_id" field is a command-unique id and is only useful if the
 
 `"thread_exit"`::
 	This event is generated when a thread exits.  It is generated
-	from *within* the thread's thread-proc (for TLS reasons).
+	from *within* the thread's thread-proc.
 +
 ------------
 {
@@ -816,6 +769,73 @@ The "value" field may be an integer or a string.
 }
 ------------
 
+`"th_timer"`::
+	This event logs the amount of time that a stopwatch timer was
+	running in the thread.  This event is generated when a thread
+	exits for timers that requested per-thread events.
++
+------------
+{
+	"event":"th_timer",
+	...
+	"category":"my_category",
+	"name":"my_timer",
+	"intervals":5,         # number of time it was started/stopped
+	"t_total":0.052741,    # total time in seconds it was running
+	"t_min":0.010061,      # shortest interval
+	"t_max":0.011648       # longest interval
+}
+------------
+
+`"timer"`::
+	This event logs the amount of time that a stopwatch timer was
+	running aggregated across all threads.  This event is generated
+	when the process exits.
++
+------------
+{
+	"event":"timer",
+	...
+	"category":"my_category",
+	"name":"my_timer",
+	"intervals":5,         # number of time it was started/stopped
+	"t_total":0.052741,    # total time in seconds it was running
+	"t_min":0.010061,      # shortest interval
+	"t_max":0.011648       # longest interval
+}
+------------
+
+`"th_counter"`::
+	This event logs the value of a counter variable in a thread.
+	This event is generated when a thread exits for counters that
+	requested per-thread events.
++
+------------
+{
+	"event":"th_counter",
+	...
+	"category":"my_category",
+	"name":"my_counter",
+	"count":23
+}
+------------
+
+`"counter"`::
+	This event logs the value of a counter variable across all threads.
+	This event is generated when the process exits.  The total value
+	reported here is the sum across all threads.
++
+------------
+{
+	"event":"counter",
+	...
+	"category":"my_category",
+	"name":"my_counter",
+	"count":23
+}
+------------
+
+
 == Example Trace2 API Usage
 
 Here is a hypothetical usage of the Trace2 API showing the intended
@@ -1206,7 +1226,7 @@ worked on 508 items at offset 2032.  Thread "th04" worked on 508 items
 at offset 508.
 +
 This example also shows that thread names are assigned in a racy manner
-as each thread starts and allocates TLS storage.
+as each thread starts.
 
 Config (def param) Events::
 
@@ -1247,6 +1267,60 @@ d0 | main                     | data         | r0  |  0.002126 |  0.002126 | fsy
 d0 | main                     | exit         |     |  0.000470 |           |              | code:0
 d0 | main                     | atexit       |     |  0.000477 |           |              | code:0
 ----------------
+
+Stopwatch Timer Events::
+
+	Measure the time spent in a function call or span of code
+	that might be called from many places within the code
+	throughout the life of the process.
++
+----------------
+static void expensive_function(void)
+{
+	trace2_timer_start(TRACE2_TIMER_ID_TEST1);
+	...
+	sleep_millisec(1000); // Do something expensive
+	...
+	trace2_timer_stop(TRACE2_TIMER_ID_TEST1);
+}
+
+static int ut_100timer(int argc, const char **argv)
+{
+	...
+
+	expensive_function();
+
+	// Do something else 1...
+
+	expensive_function();
+
+	// Do something else 2...
+
+	expensive_function();
+
+	return 0;
+}
+----------------
++
+In this example, we measure the total time spent in
+`expensive_function()` regardless of when it is called
+in the overall flow of the program.
++
+----------------
+$ export GIT_TRACE2_PERF_BRIEF=1
+$ export GIT_TRACE2_PERF=~/log.perf
+$ t/helper/test-tool trace2 100timer 3 1000
+...
+$ cat ~/log.perf
+d0 | main                     | version      |     |           |           |              | ...
+d0 | main                     | start        |     |  0.001453 |           |              | t/helper/test-tool trace2 100timer 3 1000
+d0 | main                     | cmd_name     |     |           |           |              | trace2 (trace2)
+d0 | main                     | exit         |     |  3.003667 |           |              | code:0
+d0 | main                     | timer        |     |           |           | test         | name:test1 intervals:3 total:3.001686 min:1.000254 max:1.000929
+d0 | main                     | atexit       |     |  3.003796 |           |              | code:0
+----------------
+
+
 == Future Work
 
 === Relationship to the Existing Trace Api (api-trace.txt)