trace: convert docs to rST and feature "log" backend in quickstart
v2 cover trace: convert docs to rST and feature "log" backend in quickstart
v2:
* Simplify quickstart for the "log" trace backend that is enabled by default [Peter]
* Don't show ./configure --enable-trace-backends=log example since it's built by default (changed to --enable-trace-backends=simple,dtrace) [Peter]
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} | 185 ++++++++++++++----------
2 files changed, 107 insertions(+), 79 deletions(-)
rename docs/devel/{tracing.txt => tracing.rst} (84%)Signature · 1 line
2.29.2
PATCH v2 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.29.2
PATCH v2 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.29.2
Re: [PATCH v2 2/3] tracing: convert documentation to rST
Quoted 4 lines · Stefan Hajnoczi
This is a simple rST conversion of the documentation.
Reviewed-by Peter Maydell <[email protected]>Signed-off-by Stefan Hajnoczi <[email protected]>
Signature · 1 line
Alex Bennée
PATCH v2 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 | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-)
docs/devel/tracing.rst +18 -17
@@ -11,22 +11,22 @@ for debugging, profiling, and observing execution. Quickstart ========== -1. Build with the 'simple' trace backend:: +Enable tracing of ``memory_region_ops_read`` and ``memory_region_ops_write`` +events:: - ./configure --enable-trace-backends=simple - make + $ qemu --trace "memory_region_ops_*" ... + ... + [email protected]:memory_region_ops_read cpu 0 mr 0x562fdfbb3820 addr 0x3cc value 0x67 size 1 + [email protected]:memory_region_ops_write cpu 0 mr 0x562fdfbd2f00 addr 0x3d4 value 0x70e size 2 -2. Create a file with the events you want to trace:: +This output comes from the "log" trace backend that is enabled by default when +``./configure --enable-trace-backends=BACKENDS`` was not explicitly specified. - echo memory_region_ops_read >/tmp/events +More than one trace event pattern can be specified by providing a file +instead:: -3. Run the virtual machine to produce a trace file:: - - 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> + $ echo "memory_region_ops_*" >/tmp/events + $ qemu --trace events=/tmp/events ... Trace events ============
@@ -195,7 +195,7 @@ script. The trace backends are chosen at configure time:: - ./configure --enable-trace-backends=simple + ./configure --enable-trace-backends=simple,dtrace 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 +227,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.29.2
Re: [PATCH v2 3/3] trace: recommend "log" backend for getting started with tracing
Quoted 27 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 | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-)docs/devel/tracing.rst +4
-3@@ -11,22 +11,22 @@ for debugging, profiling, and observing execution. Quickstart ========== -1. Build with the 'simple' trace backend:: +Enable tracing of ``memory_region_ops_read`` and ``memory_region_ops_write`` +events:: - ./configure --enable-trace-backends=simple - make + $ qemu --trace "memory_region_ops_*" ... + ...
docs/devel/tracing.rst for debugging, profiling, and observing execution. · line 26
Quoted 10 lines
docs/devel/tracing.rst +6
-2+ [email protected]:memory_region_ops_read cpu 0 mr 0x562fdfbb3820 addr 0x3cc value 0x67 size 1 + [email protected]:memory_region_ops_write cpu 0 mr 0x562fdfbd2f00 addr 0x3d4 value 0x70e size 2 -2. Create a file with the events you want to trace:: +This output comes from the "log" trace backend that is enabled by default when +``./configure --enable-trace-backends=BACKENDS`` was not explicitly specified. - echo memory_region_ops_read >/tmp/events +More than one trace event pattern can be specified by providing a file +instead::
Does --trace really not let you specify more than one pattern without resorting to putting them into a file? That sounds like a deficiency compared to -d (which allows -d trace:PATTERN,trace:PATTERN...) that we could look at fixing...
Anyway,
thanks
-- PMM
Re: [PATCH v2 3/3] trace: recommend "log" backend for getting started with tracing
Quoted 35 lines · Peter Maydell
Quoted 34 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 | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-)docs/devel/tracing.rst +8
-4@@ -11,22 +11,22 @@ for debugging, profiling, and observing execution. Quickstart ========== -1. Build with the 'simple' trace backend:: +Enable tracing of ``memory_region_ops_read`` and ``memory_region_ops_write`` +events:: - ./configure --enable-trace-backends=simple - make + $ qemu --trace "memory_region_ops_*" ... + ... + [email protected]:memory_region_ops_read cpu 0 mr 0x562fdfbb3820 addr 0x3cc value 0x67 size 1 + [email protected]:memory_region_ops_write cpu 0 mr 0x562fdfbd2f00 addr 0x3d4 value 0x70e size 2 -2. Create a file with the events you want to trace:: +This output comes from the "log" trace backend that is enabled by default when +``./configure --enable-trace-backends=BACKENDS`` was not explicitly specified.
Quoted 8 lines
docs/devel/tracing.rst for debugging, profiling, and observing execution. · line 26
Quoted 3 lines
docs/devel/tracing.rst +2
-1- echo memory_region_ops_read >/tmp/events +More than one trace event pattern can be specified by providing a file +instead::Does --trace really not let you specify more than one pattern without resorting to putting them into a file? That sounds like a deficiency compared to -d (which allows -d trace:PATTERN,trace:PATTERN...) that we could look at fixing...
Ir's possible to give more patterns in multiple options, I'm using that, such as:
-trace enable="pci*" -trace enable="ide*"
For a lot of patterns using a file may be clearer though.
This reminds me to the plainlog backend I've submitted. What happened to that? See:
https://lists.nongnu.org/archive/html/qemu-devel/2020-06/msg07296.html
I'd like a solution that can be set at compile time and does not need another command line option to turn off time stamps. (Timestamps are annoyong when comparing logs that's often necessary to check changes.) I'm still using my plainlog patch but I have to disable that when bisecting.
Regards,
BALATON Zoltan
Quoted 7 lines
Anyway,
Reviewed-by Peter Maydell <[email protected]>thanks
-- PMM
Re: [PATCH v2 3/3] trace: recommend "log" backend for getting started with tracing
Quoted 55 lines · BALATON Zoltan
Quoted 35 lines · Peter Maydell
Quoted 34 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 | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-)docs/devel/tracing.rst +8
-4@@ -11,22 +11,22 @@ for debugging, profiling, and observing execution. Quickstart ========== -1. Build with the 'simple' trace backend:: +Enable tracing of ``memory_region_ops_read`` and ``memory_region_ops_write`` +events:: - ./configure --enable-trace-backends=simple - make + $ qemu --trace "memory_region_ops_*" ... + ... + [email protected]:memory_region_ops_read cpu 0 mr 0x562fdfbb3820 addr 0x3cc value 0x67 size 1 + [email protected]:memory_region_ops_write cpu 0 mr 0x562fdfbd2f00 addr 0x3d4 value 0x70e size 2 -2. Create a file with the events you want to trace:: +This output comes from the "log" trace backend that is enabled by default when +``./configure --enable-trace-backends=BACKENDS`` was not explicitly specified.Quoted 8 lines
docs/devel/tracing.rst for debugging, profiling, and observing execution. · line 26
Quoted 3 lines
docs/devel/tracing.rst +2
-1- echo memory_region_ops_read >/tmp/events +More than one trace event pattern can be specified by providing a file +instead::Does --trace really not let you specify more than one pattern without resorting to putting them into a file? That sounds like a deficiency compared to -d (which allows -d trace:PATTERN,trace:PATTERN...) that we could look at fixing...
Ir's possible to give more patterns in multiple options, I'm using that, such as:
-trace enable="pci*" -trace enable="ide*"
For a lot of patterns using a file may be clearer though.
This reminds me to the plainlog backend I've submitted. What happened to that? See:
Quoted 6 lines
https://lists.nongnu.org/archive/html/qemu-devel/2020-06/msg07296.html
I'd like a solution that can be set at compile time and does not need another command line option to turn off time stamps. (Timestamps are annoyong when comparing logs that's often necessary to check changes.) I'm still using my plainlog patch but I have to disable that when bisecting.
Thanks for reminding me. I don't remember what happened to that, sorry!
I will revisit the plainlog series and let you know.
Stefan
Stefan Hajnoczi
AppliedQuoted 17 lines · Stefan Hajnoczi
v2:
* Simplify quickstart for the "log" trace backend that is enabled by default [Peter]
* Don't show ./configure --enable-trace-backends=log example since it's built by default (changed to --enable-trace-backends=simple,dtrace) [Peter]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
Quoted 8 lines
docs/devel/index.rst | 1 + docs/devel/{tracing.txt => tracing.rst} | 185 ++++++++++++++---------- 2 files changed, 107 insertions(+), 79 deletions(-) rename docs/devel/{tracing.txt => tracing.rst} (84%)Signature · 1 line
2.29.2
Thanks, applied to my tracing tree:
https://gitlab.com/stefanha/qemu/commits/tracing
Stefan