The "simple" backend is actually more complicated to use than the "log"
backend. Update the quickstart documentation to feature the "log"
backend instead of the "simple" backend.

Suggested-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/devel/tracing.rst | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/docs/devel/tracing.rst b/docs/devel/tracing.rst
index 76cc1b24fa..039a0bb267 100644
--- a/docs/devel/tracing.rst
+++ b/docs/devel/tracing.rst
@@ -11,9 +11,9 @@ for debugging, profiling, and observing execution.
 Quickstart
 ==========
 
-1. Build with the 'simple' trace backend::
+1. Build with the 'log' trace backend::
 
-    ./configure --enable-trace-backends=simple
+    ./configure --enable-trace-backends=log
     make
 
 2. Create a file with the events you want to trace::
@@ -24,10 +24,6 @@ Quickstart
 
     qemu --trace events=/tmp/events ... # your normal QEMU invocation
 
-4. Pretty-print the binary trace file::
-
-    ./scripts/simpletrace.py trace-events-all trace-* # Override * with QEMU <pid>
-
 Trace events
 ============
 
@@ -195,7 +191,7 @@ script.
 
 The trace backends are chosen at configure time::
 
-    ./configure --enable-trace-backends=simple
+    ./configure --enable-trace-backends=log
 
 For a list of supported trace backends, try ./configure --help or see below.
 If multiple backends are enabled, the trace is sent to them all.
@@ -227,10 +223,11 @@ uses DPRINTF().
 Simpletrace
 -----------
 
-The "simple" backend supports common use cases and comes as part of the QEMU
-source tree.  It may not be as powerful as platform-specific or third-party
-trace backends but it is portable.  This is the recommended trace backend
-unless you have specific needs for more advanced backends.
+The "simple" backend writes binary trace logs to a file from a thread, making
+it lower overhead than the "log" backend. A Python API is available for writing
+offline trace file analysis scripts. It may not be as powerful as
+platform-specific or third-party trace backends but it is portable and has no
+special library dependencies.
 
 Monitor commands
 ~~~~~~~~~~~~~~~~
-- 
2.28.0

On Wed, 9 Dec 2020 at 17:42, Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> The "simple" backend is actually more complicated to use than the "log"
> backend. Update the quickstart documentation to feature the "log"
> backend instead of the "simple" backend.
>
> Suggested-by: Peter Maydell <peter.maydell@linaro.org>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/devel/tracing.rst | 19 ++++++++-----------
>  1 file changed, 8 insertions(+), 11 deletions(-)
>
> diff --git a/docs/devel/tracing.rst b/docs/devel/tracing.rst
> index 76cc1b24fa..039a0bb267 100644
> --- a/docs/devel/tracing.rst
> +++ b/docs/devel/tracing.rst
> @@ -11,9 +11,9 @@ for debugging, profiling, and observing execution.
>  Quickstart
>  ==========
>
> -1. Build with the 'simple' trace backend::
> +1. Build with the 'log' trace backend::
>
> -    ./configure --enable-trace-backends=simple
> +    ./configure --enable-trace-backends=log
>      make

Isn't this the default ?

It seems to me that the real "quickstart" is
"your QEMU binary was likely already built with the log backend,
so all you need to do is pass it '-trace eventname -trace eventname'
or '-trace some-pattern*'" (or whatever the syntax is: I
usually use -d trace=something but I assume we'd rather suggest
-trace to new users ?)

We can suggest also "if you have a lot of events you might find
it useful to put them in a file and use --trace events=file"
but IME that's not the common case for "getting started with
just outputting trace events" because you can usually enable
a whole device's trace events with one suitable glob pattern.

>  2. Create a file with the events you want to trace::
> @@ -24,10 +24,6 @@ Quickstart
>
>      qemu --trace events=/tmp/events ... # your normal QEMU invocation
>
> -4. Pretty-print the binary trace file::
> -
> -    ./scripts/simpletrace.py trace-events-all trace-* # Override * with QEMU <pid>
> -
>  Trace events
>  ============
>
> @@ -195,7 +191,7 @@ script.
>
>  The trace backends are chosen at configure time::
>
> -    ./configure --enable-trace-backends=simple
> +    ./configure --enable-trace-backends=log

'log' is the default so we don't need to specifically suggest people
select it as a configure argument.

>  For a list of supported trace backends, try ./configure --help or see below.
>  If multiple backends are enabled, the trace is sent to them all.
> @@ -227,10 +223,11 @@ uses DPRINTF().
>  Simpletrace
>  -----------
>
> -The "simple" backend supports common use cases and comes as part of the QEMU
> -source tree.  It may not be as powerful as platform-specific or third-party
> -trace backends but it is portable.  This is the recommended trace backend
> -unless you have specific needs for more advanced backends.
> +The "simple" backend writes binary trace logs to a file from a thread, making
> +it lower overhead than the "log" backend. A Python API is available for writing
> +offline trace file analysis scripts. It may not be as powerful as
> +platform-specific or third-party trace backends but it is portable and has no
> +special library dependencies.
>
>  Monitor commands
>  ~~~~~~~~~~~~~~~~

thanks
-- PMM

On Fri, Dec 11, 2020 at 03:06:17PM +0000, Peter Maydell wrote:
> On Wed, 9 Dec 2020 at 17:42, Stefan Hajnoczi <stefanha@redhat.com> wrote:
> >
> > The "simple" backend is actually more complicated to use than the "log"
> > backend. Update the quickstart documentation to feature the "log"
> > backend instead of the "simple" backend.
> >
> > Suggested-by: Peter Maydell <peter.maydell@linaro.org>
> > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> > ---
> >  docs/devel/tracing.rst | 19 ++++++++-----------
> >  1 file changed, 8 insertions(+), 11 deletions(-)
> >
> > diff --git a/docs/devel/tracing.rst b/docs/devel/tracing.rst
> > index 76cc1b24fa..039a0bb267 100644
> > --- a/docs/devel/tracing.rst
> > +++ b/docs/devel/tracing.rst
> > @@ -11,9 +11,9 @@ for debugging, profiling, and observing execution.
> >  Quickstart
> >  ==========
> >
> > -1. Build with the 'simple' trace backend::
> > +1. Build with the 'log' trace backend::
> >
> > -    ./configure --enable-trace-backends=simple
> > +    ./configure --enable-trace-backends=log
> >      make
> 
> Isn't this the default ?
> 
> It seems to me that the real "quickstart" is
> "your QEMU binary was likely already built with the log backend,
> so all you need to do is pass it '-trace eventname -trace eventname'
> or '-trace some-pattern*'" (or whatever the syntax is: I
> usually use -d trace=something but I assume we'd rather suggest
> -trace to new users ?)
> 
> We can suggest also "if you have a lot of events you might find
> it useful to put them in a file and use --trace events=file"
> but IME that's not the common case for "getting started with
> just outputting trace events" because you can usually enable
> a whole device's trace events with one suitable glob pattern.

Good idea, I'll simplify the quickstart section.

> >  2. Create a file with the events you want to trace::
> > @@ -24,10 +24,6 @@ Quickstart
> >
> >      qemu --trace events=/tmp/events ... # your normal QEMU invocation
> >
> > -4. Pretty-print the binary trace file::
> > -
> > -    ./scripts/simpletrace.py trace-events-all trace-* # Override * with QEMU <pid>
> > -
> >  Trace events
> >  ============
> >
> > @@ -195,7 +191,7 @@ script.
> >
> >  The trace backends are chosen at configure time::
> >
> > -    ./configure --enable-trace-backends=simple
> > +    ./configure --enable-trace-backends=log
> 
> 'log' is the default so we don't need to specifically suggest people
> select it as a configure argument.

Will fix.