Re: [PATCH 01/14] trace2: Documentation/technical/api-trace2.txt

> On Tue, Jan 22, 2019 at 01:22:12PM -0800, Jeff Hostetler via GitGitGadget wrote:
> > From: Jeff Hostetler <jeffhost@microsoft.com>
> > 
> > Created design document for Trace2 feature.
> > 
> > Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com>
> > ---
> >  Documentation/technical/api-trace2.txt | 1158 ++++++++++++++++++++++++
> >  1 file changed, 1158 insertions(+)
> >  create mode 100644 Documentation/technical/api-trace2.txt
> > 
> > diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt
> > new file mode 100644
> > index 0000000000..501fd770f2
> > --- /dev/null
> > +++ b/Documentation/technical/api-trace2.txt
> > @@ -0,0 +1,1158 @@
> > +Trace2 API
> > +==========
> > +
> > +The Trace2 API can be used to print debug, performance, and telemetry
> > +information to stderr or a file.  The Trace2 feature is inactive unless
> > +explicitly enabled by setting one or more of the `GIT_TR2`, `GIT_TR2_PERF`,
> > +or `GIT_TR2_EVENT` environment variables.
> > +
> > +The Trace2 API is intended to replace the existing (Trace1)
> > +printf-style tracing provided by the existing `GIT_TRACE` and
> > +`GIT_TRACE_PERFORMANCE` facilities.  During initial implementation,
> > +Trace2 and Trace1 may operate in parallel.
> 
> Speaking of replacing Trace1, I couldn't find (or managed to overlook)
> the Trace2 equivalent of the good old "plain"
> 
>   trace_printf("Uh-oh!");
> 
> which is my go-to tool when chasing elusive heisenbugs and attempting
> to understand racy situations and flaky tests.