Users can inherit from the simpletrace.Analyzer class and receive
callbacks when events of interest occur in a trace file.  The method
signature is a little magic because the timestamp and pid arguments are
optional.  Document this.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 scripts/simpletrace.py | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/scripts/simpletrace.py b/scripts/simpletrace.py
index 4c99004..d60b3a0 100755
--- a/scripts/simpletrace.py
+++ b/scripts/simpletrace.py
@@ -116,7 +116,28 @@ class Analyzer(object):
     is invoked.
 
     If a method matching a trace event name exists, it is invoked to process
-    that trace record.  Otherwise the catchall() method is invoked."""
+    that trace record.  Otherwise the catchall() method is invoked.
+
+    Example:
+    The following method handles the runstate_set(int new_state) trace event::
+
+      def runstate_set(self, new_state):
+          ...
+
+    The method can also take a timestamp argument before the trace event
+    arguments::
+
+      def runstate_set(self, timestamp, new_state):
+          ...
+
+    Timestamps have the uint64_t type and are in nanoseconds.
+
+    The pid can be included in addition to the timestamp and is useful when
+    dealing with traces from multiple processes::
+
+      def runstate_set(self, timestamp, pid, new_state):
+          ...
+    """
 
     def begin(self):
         """Called at the start of the trace."""
-- 
2.9.3

Stefan Hajnoczi <stefanha@redhat.com> writes:

> Users can inherit from the simpletrace.Analyzer class and receive
> callbacks when events of interest occur in a trace file.  The method
> signature is a little magic because the timestamp and pid arguments are
> optional.  Document this.
>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

> ---
>  scripts/simpletrace.py | 23 ++++++++++++++++++++++-
>  1 file changed, 22 insertions(+), 1 deletion(-)
>
> diff --git a/scripts/simpletrace.py b/scripts/simpletrace.py
> index 4c99004..d60b3a0 100755
> --- a/scripts/simpletrace.py
> +++ b/scripts/simpletrace.py
> @@ -116,7 +116,28 @@ class Analyzer(object):
>      is invoked.
>
>      If a method matching a trace event name exists, it is invoked to process
> -    that trace record.  Otherwise the catchall() method is invoked."""
> +    that trace record.  Otherwise the catchall() method is invoked.
> +
> +    Example:
> +    The following method handles the runstate_set(int new_state) trace event::
> +
> +      def runstate_set(self, new_state):
> +          ...
> +
> +    The method can also take a timestamp argument before the trace event
> +    arguments::
> +
> +      def runstate_set(self, timestamp, new_state):
> +          ...
> +
> +    Timestamps have the uint64_t type and are in nanoseconds.
> +
> +    The pid can be included in addition to the timestamp and is useful when
> +    dealing with traces from multiple processes::
> +
> +      def runstate_set(self, timestamp, pid, new_state):
> +          ...
> +    """
>
>      def begin(self):
>          """Called at the start of the trace."""


--
Alex Bennée

On Tue, Apr 11, 2017 at 10:56:54AM +0100, Stefan Hajnoczi wrote:
> Users can inherit from the simpletrace.Analyzer class and receive
> callbacks when events of interest occur in a trace file.  The method
> signature is a little magic because the timestamp and pid arguments are
> optional.  Document this.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  scripts/simpletrace.py | 23 ++++++++++++++++++++++-
>  1 file changed, 22 insertions(+), 1 deletion(-)

Thanks, applied to my tracing-next tree:
https://github.com/stefanha/qemu/commits/tracing-next

Stefan