trace: convert docs to rST and feature "log" backend in quickstart
cover trace: convert docs to rST and feature "log" backend in quickstart
Convert tracing.txt to rST and add it to the generated developer documentation.
Peter Maydell suggested making the "log" backend the recommended backend in the quickstart documentation. It's easier to use than the "simple" backend. The final patch updates the documentation to do this.
Stefan Hajnoczi (3):
trace: fix simpletrace doc mismerge
tracing: convert documentation to rST
trace: recommend "log" backend for getting started with tracing
docs/devel/index.rst | 1 +
docs/devel/{tracing.txt => tracing.rst} | 175 ++++++++++++++----------
2 files changed, 100 insertions(+), 76 deletions(-)
rename docs/devel/{tracing.txt => tracing.rst} (86%)Signature · 1 line
2.28.0
PATCH 1/3 trace: fix simpletrace doc mismerge
The simpletrace documentation section was accidentally split when the ftrace section was introduced. Move the simpletrace-specific documentation back into the simpletrace section.
--- docs/devel/tracing.txt | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-)
docs/devel/tracing.txt +17 -17
@@ -218,6 +218,23 @@ 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. +==== Monitor commands ==== + +* trace-file on|off|flush|set <path> + Enable/disable/flush the trace file or set the trace file name. + +==== Analyzing trace files ==== + +The "simple" backend produces binary trace files that can be formatted with the +simpletrace.py script. The script takes the "trace-events-all" file and the +binary trace: + + ./scripts/simpletrace.py trace-events-all trace-12345 + +You must ensure that the same "trace-events-all" file was used to build QEMU, +otherwise trace event declarations may have changed and output will not be +consistent. + === Ftrace === The "ftrace" backend writes trace data to ftrace marker. This effectively
@@ -246,23 +263,6 @@ NOTE: syslog may squash duplicate consecutive trace events and apply rate Restriction: "syslog" backend is restricted to POSIX compliant OS. -==== Monitor commands ==== - -* trace-file on|off|flush|set <path> - Enable/disable/flush the trace file or set the trace file name. - -==== Analyzing trace files ==== - -The "simple" backend produces binary trace files that can be formatted with the -simpletrace.py script. The script takes the "trace-events-all" file and the -binary trace: - - ./scripts/simpletrace.py trace-events-all trace-12345 - -You must ensure that the same "trace-events-all" file was used to build QEMU, -otherwise trace event declarations may have changed and output will not be -consistent. - === LTTng Userspace Tracer === The "ust" backend uses the LTTng Userspace Tracer library. There are no
Signature · 1 line
2.28.0
Re: [PATCH 1/3] trace: fix simpletrace doc mismerge
Quoted 10 lines · Stefan Hajnoczi
The simpletrace documentation section was accidentally split when the ftrace section was introduced. Move the simpletrace-specific documentation back into the simpletrace section.
Fixes e64dd5efb2c6d522a3bc9d096cd49a4e53f0ae10 ("trace: document ftrace backend")Signed-off-by Stefan Hajnoczi <[email protected]>--- docs/devel/tracing.txt | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-)
thanks
-- PMM
PATCH 2/3 tracing: convert documentation to rST
In reply to Stefan HajnocziThis is a simple rST conversion of the documentation.
---
docs/devel/index.rst | 1 +
docs/devel/{tracing.txt => tracing.rst} | 134 ++++++++++++++----------
2 files changed, 81 insertions(+), 54 deletions(-)
rename docs/devel/{tracing.txt => tracing.rst} (89%)docs/devel/index.rst +1 -0
@@ -27,6 +27,7 @@ Contents: secure-coding-practices tcg tcg-icount + tracing multi-thread-tcg tcg-plugins bitops
docs/devel/tracing.rst renamed from docs/devel/tracing.txt +80 -54
365 lines not on this page · raw message
Signature · 1 line
2.28.0
Re: [PATCH 2/3] tracing: convert documentation to rST
Quoted 10 lines · Stefan Hajnoczi
This is a simple rST conversion of the documentation.
Signed-off-by Stefan Hajnoczi <[email protected]>--- docs/devel/index.rst | 1 + docs/devel/{tracing.txt => tracing.rst} | 134 ++++++++++++++---------- 2 files changed, 81 insertions(+), 54 deletions(-) rename docs/devel/{tracing.txt => tracing.rst} (89%)
thanks
-- PMM
PATCH 3/3 trace: recommend "log" backend for getting started with tracing
In reply to Stefan HajnocziThe "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.
--- docs/devel/tracing.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-)
docs/devel/tracing.rst +8 -11
@@ -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 ~~~~~~~~~~~~~~~~
Signature · 1 line
2.28.0
Re: [PATCH 3/3] trace: recommend "log" backend for getting started with tracing
Quoted 16 lines · Stefan Hajnoczi
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 <[email protected]>Signed-off-by Stefan Hajnoczi <[email protected]>--- docs/devel/tracing.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-)docs/devel/tracing.rst +0
-0
docs/devel/tracing.rst for debugging, profiling, and observing execution. · line 17
Quoted 9 lines
docs/devel/tracing.rst +2
-2@@ -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.
Quoted 13 lines
docs/devel/tracing.rst +0
-42. 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 ============
docs/devel/tracing.rst script. · line 194
Quoted 5 lines
docs/devel/tracing.rst +1
-1@@ -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.
Quoted 8 lines
docs/devel/tracing.rst +0
-2For 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
docs/devel/tracing.rst uses DPRINTF(). · line 233
Quoted 10 lines
docs/devel/tracing.rst +5
-2-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
Re: [PATCH 3/3] trace: recommend "log" backend for getting started with tracing
Quoted 36 lines · Peter Maydell
Quoted 16 lines · Stefan Hajnoczi
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 <[email protected]>Signed-off-by Stefan Hajnoczi <[email protected]>--- docs/devel/tracing.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-)docs/devel/tracing.rst +0
-0docs/devel/tracing.rst for debugging, profiling, and observing execution. · line 17
Quoted 9 lines
docs/devel/tracing.rst +2
-2@@ -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 makeIsn'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 ?)
Quoted 5 lines
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.
Quoted 14 lines
Quoted 14 lines
docs/devel/tracing.rst +0
-42. 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.
Quoted 7 lines
docs/devel/tracing.rst script. · line 194
Quoted 4 lines
docs/devel/tracing.rst +1
-1The 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.