[Qemu-devel] [RFC 0/5] QMP interfaces for tracing

[Qemu-devel] [RFC 0/5] QMP interfaces for tracing

[Prerna Saxena]

As suggested by Luiz, I'm posting this set of documentation patches that
elucidate for proposed QMP interfaces for tracing.

QMP commands :
* trace-event : to toggle state of a trace-event.
* set-trace-file : to set a new output file for tracing; enable/disable 
                   writing traces to file; flush buffer contents to file.
* Query Commands :
------------------
   * query-trace : to list current contents of trace buffer that havent 
                   been written to file.
   * query-trace-events : to list all available trace-events and their status.
   * query-trace-file : to display currently set trace file and its status.

-- 
Prerna Saxena

Linux Technology Centre,
IBM Systems and Technology Lab,
Bangalore, India

[Qemu-devel] [RFC][PATCH 1/5] query-trace command

[Prerna Saxena]

QMP interface "query-trace" to list current contents of trace-buffer.
( Analogous to hmp command : info trace )


Signed-off-by: Prerna Saxena <prerna@linux.vnet.ibm.com>
---
 qmp-commands.hx |   51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 51 insertions(+), 0 deletions(-)

diff --git a/qmp-commands.hx b/qmp-commands.hx
index 793cf1c..f289064 100644
--- a/qmp-commands.hx
+++ b/qmp-commands.hx
@@ -1539,3 +1539,54 @@ Example:
 
 EQMP
 
+SQMP
+query-trace
+-------------
+
+Show current contents of trace buffer.
+
+Returns a json-array of json-objects containing the following data:
+
+- "event_id": Event ID for the trace-event(json-int)
+- "timestamp": trace timestamp in ns (json-int)
+- "trace-arg": A json-object containing args logged by the trace-event:
+    - "arg1": First trace argument (json-int)
+    - "arg2": Second trace argument (json-int)
+    - "arg3": Third trace argument (json-int)
+    - "arg4": Fourth trace argument (json-int)
+    - "arg5": Fifth trace argument (json-int)
+    - "arg6": Sixth trace argument (json-int)
+
+Example:
+
+-> { "execute": "query-trace" }
+<- {
+      "return":[
+         {
+            "event": 22,
+            "timestamp": 129456235912365,
+            "trace-arg":{
+               "arg1": 886,
+               "arg2": 80,
+               "arg3": 0,
+               "arg4": 0,
+               "arg5": 0,
+               "arg6": 0,
+            }
+         },
+         {
+            "event": 22,
+            "timestamp": 129456235973407,
+            "trace-arg":{
+               "arg1": 886,
+               "arg2": 80,
+               "arg3": 0,
+               "arg4": 0,
+               "arg5": 0,
+               "arg6": 0
+            },
+         }
+      ]
+   }
+
+EQMP
-- 
1.7.2.3



-- 
Prerna Saxena

Linux Technology Centre,
IBM Systems and Technology Lab,
Bangalore, India

[Qemu-devel] [RFC][PATCH 2/5] query-trace-events

[Prerna Saxena]

'query-trace-events' : QMP interface to display currently available 
trace-events with their state.
( Analogous to hmp command : info trace-events )

Signed-off-by: Prerna Saxena <prerna@linux.vnet.ibm.com>
---
 qmp-commands.hx |   32 ++++++++++++++++++++++++++++++++
 1 files changed, 32 insertions(+), 0 deletions(-)

diff --git a/qmp-commands.hx b/qmp-commands.hx
index f289064..e079eef 100644
--- a/qmp-commands.hx
+++ b/qmp-commands.hx
@@ -1590,3 +1590,35 @@ Example:
    }
 
 EQMP
+
+SQMP
+query-trace-events
+------------------
+
+Show all available trace-events & their state.
+
+Returns a json-array of json-objects containing the following data:
+
+- "name": Name of Trace-event (json-string)
+- "event_id": Event ID of Trace-event (json-int)
+- "state": State of trace-event (json-bool)
+
+Example:
+
+-> { "execute": "query-trace-events" }
+<- {
+      "return":[
+         {
+            "name": "qemu_malloc",
+            "event_id": 0,
+            "state": false
+         },
+         {
+            "name": "qemu_realloc",
+            "event_id": 1,
+            "state": false
+         },
+      ]
+   }
+
+EQMP
-- 
1.7.2.3



-- 
Prerna Saxena

Linux Technology Centre,
IBM Systems and Technology Lab,
Bangalore, India

[Qemu-devel] [RFC] [PATCH 3/5] query-trace-file

[Prerna Saxena]

'query-trace-file' : QMP interface to find currently set trace file and 
its status.
(Analogous to hmp command : trace-file)

Signed-off-by: Prerna Saxena <prerna@linux.vnet.ibm.com>
---
 qmp-commands.hx |   24 ++++++++++++++++++++++++
 1 files changed, 24 insertions(+), 0 deletions(-)

diff --git a/qmp-commands.hx b/qmp-commands.hx
index e079eef..7e95f4e 100644
--- a/qmp-commands.hx
+++ b/qmp-commands.hx
@@ -1622,3 +1622,27 @@ Example:
    }
 
 EQMP
+
+SQMP
+query-trace-file
+----------------
+
+Display the trace file name to which trace data is currently logged, and its
+status.
+
+Returns a json-object containing the following data:
+
+- "trace-file": Name + path of Trace-file (json-string)
+- "enabled": State of trace-event (json-bool)
+
+Example:
+
+-> { "execute": "query-trace-file" }
+<- {
+      "return":{
+         "trace-file": "/tmp/trace-26609",
+         "enabled": true
+      }
+   }
+
+EQMP
-- 
1.7.2.3



-- 
Prerna Saxena

Linux Technology Centre,
IBM Systems and Technology Lab,
Bangalore, India

[Qemu-devel] [RFC][PATCH 4/5] trace-event

[Prerna Saxena]

trace-event : QMP interface to change state of a trace-event.
(Analogous to hmp command : trace-event )

Signed-off-by: Prerna Saxena <prerna@linux.vnet.ibm.com>
---
 qmp-commands.hx |   32 ++++++++++++++++++++++++++++++++
 1 files changed, 32 insertions(+), 0 deletions(-)

diff --git a/qmp-commands.hx b/qmp-commands.hx
index 7e95f4e..f2008e8 100644
--- a/qmp-commands.hx
+++ b/qmp-commands.hx
@@ -761,6 +761,38 @@ Example:
 
 Note: This command must be issued before issuing any other command.
 
+EQMP
+
+    {
+        .name       = "trace-event",
+        .args_type  = "name:s,option:b",
+        .params     = "name on|off",
+        .help       = "changes state of a specific trace event",
+        .user_print = monitor_user_noop,
+        .mhandler.cmd_new = do_change_trace_event_state_qmp,
+    },
+
+SQMP
+trace-event
+-----------
+
+Change state of a trace-event.
+
+Arguments:
+
+- "name": name of trace-event (json-string)
+- "enable": New state to be set for the trace-event (json-bool)
+
+Example:
+
+-> { "execute": "trace-event", "arguments": { "name": "ABC", "enable":false } }
+<- { "return": {} }
+
+Notes:
+
+(1) The 'query-trace-events' command should be used to check the new state
+    of the trace-event.
+
 3. Query Commands
 =================
 
-- 
1.7.2.3



-- 
Prerna Saxena

Linux Technology Centre,
IBM Systems and Technology Lab,
Bangalore, India

[Qemu-devel] Re: [RFC][PATCH 4/5] trace-event

[Stefan Hajnoczi]

On Thu, Oct 21, 2010 at 03:10:18PM +0530, Prerna Saxena wrote:
> trace-event : QMP interface to change state of a trace-event.
> (Analogous to hmp command : trace-event )
> 
> Signed-off-by: Prerna Saxena <prerna@linux.vnet.ibm.com>
> ---
>  qmp-commands.hx |   32 ++++++++++++++++++++++++++++++++
>  1 files changed, 32 insertions(+), 0 deletions(-)
> 
> diff --git a/qmp-commands.hx b/qmp-commands.hx
> index 7e95f4e..f2008e8 100644
> --- a/qmp-commands.hx
> +++ b/qmp-commands.hx
> @@ -761,6 +761,38 @@ Example:
> 
>  Note: This command must be issued before issuing any other command.
> 
> +EQMP
> +
> +    {
> +        .name       = "trace-event",
> +        .args_type  = "name:s,option:b",
> +        .params     = "name on|off",
> +        .help       = "changes state of a specific trace event",
> +        .user_print = monitor_user_noop,
> +        .mhandler.cmd_new = do_change_trace_event_state_qmp,
> +    },
> +
> +SQMP
> +trace-event
> +-----------
> +
> +Change state of a trace-event.

The name is a little odd because it has no verb.  How about
set-trace-event or enable-trace-event?

Stefan

[Qemu-devel] Re: [RFC][PATCH 4/5] trace-event

[Prerna Saxena]

On 10/22/2010 08:57 PM, Stefan Hajnoczi wrote:
> On Thu, Oct 21, 2010 at 03:10:18PM +0530, Prerna Saxena wrote:
>> trace-event : QMP interface to change state of a trace-event.
>> (Analogous to hmp command : trace-event )
>>
>> Signed-off-by: Prerna Saxena<prerna@linux.vnet.ibm.com>
>> ---
>>   qmp-commands.hx |   32 ++++++++++++++++++++++++++++++++
>>   1 files changed, 32 insertions(+), 0 deletions(-)
>>
>> diff --git a/qmp-commands.hx b/qmp-commands.hx
>> index 7e95f4e..f2008e8 100644
>> --- a/qmp-commands.hx
>> +++ b/qmp-commands.hx
>> @@ -761,6 +761,38 @@ Example:
>>
>>   Note: This command must be issued before issuing any other command.
>>
>> +EQMP
>> +
>> +    {
>> +        .name       = "trace-event",
>> +        .args_type  = "name:s,option:b",
>> +        .params     = "name on|off",
>> +        .help       = "changes state of a specific trace event",
>> +        .user_print = monitor_user_noop,
>> +        .mhandler.cmd_new = do_change_trace_event_state_qmp,
>> +    },
>> +
>> +SQMP
>> +trace-event
>> +-----------
>> +
>> +Change state of a trace-event.
>
> The name is a little odd because it has no verb.  How about
> set-trace-event or enable-trace-event?
>

Sure, makes sense.
I'll incorporate this when I send out the next set of patches.

Thanks,
-- 
Prerna Saxena

Linux Technology Centre,
IBM Systems and Technology Lab,
Bangalore, India

[Qemu-devel] [RFC][PATCH 5/5] set-trace-file

[Prerna Saxena]

set-trace-file : QMP command to:
     - Enable/disable logging traces to file
     - Set a new output file
     - Flush a semi-filled trace-buffer to output file.


Signed-off-by: Prerna Saxena <prerna@linux.vnet.ibm.com>
---
 qmp-commands.hx |   41 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 41 insertions(+), 0 deletions(-)

diff --git a/qmp-commands.hx b/qmp-commands.hx
index f2008e8..295382f 100644
--- a/qmp-commands.hx
+++ b/qmp-commands.hx
@@ -793,6 +793,47 @@ Notes:
 (1) The 'query-trace-events' command should be used to check the new state
     of the trace-event.
 
+EQMP
+
+    {
+        .name       = "set-trace-file",
+        .args_type  = "enable:-e?,flush:-f?,filename:F?",
+        .params     = "[-e] [-f] [filename]",
+        .help       = "Sets a user-specified output file to write traces to",
+        .user_print = monitor_user_noop,
+        .mhandler.cmd_new = do_set_trace_file_qmp,
+    },
+
+SQMP
+set-trace-file
+--------------
+
+Set a new output file to log trace data to.
+
+Arguments:
+
+- "filename": name of new output file to write trace data to.
+                                      (json-string, optional)
+- "enable": if false, traces are not written to file.
+          : Only when this is 'true' that trace buffer contents get logged
+            in a file. (json-bool, optional, defaults to false)
+- "flush": if true, contents of trace buffer are immediately written to file,
+           instead of waiting for the buffer to be full.
+           (json-bool, optional, defaults to false)
+
+Example:
+1. Set a new trace-file:
+-> { "execute": "set-trace-file", "arguments": { "filename": "ABC",
+                                                 "enable":true } }
+<- { "return": {} }
+
+2. Flush the current traces to file:
+-> { "execute": "set-trace-file", "arguments": { "flush": true } }
+
+Notes:
+
+(1) The 'query-trace-file' command should be used to check active trace-file.
+
 3. Query Commands
 =================
 
-- 
1.7.2.3



-- 
Prerna Saxena

Linux Technology Centre,
IBM Systems and Technology Lab,
Bangalore, India