tracing.rst neglects to document syntax of trace-events files

tracing.rst neglects to document syntax of trace-events files

[Markus Armbruster]

Almost[*] all trace-events files start with this line:

    # See docs/devel/tracing.rst for syntax documentation.

But I can't find syntax documentation there.


[*] Exceptions:
    $ git-ls-files \*/trace-events| xargs fgrep -L '# See docs/devel/tracing.rst for syntax documentation.'
    ebpf/trace-events
    hw/core/trace-events
    hw/hyperv/trace-events
    hw/mips/trace-events
    hw/net/can/trace-events
    hw/nubus/trace-events
    hw/nvme/trace-events
    hw/remote/trace-events
    hw/sh4/trace-events
    hw/ssi/trace-events
    target/arm/hvf/trace-events
    target/riscv/trace-events
    target/s390x/kvm/trace-events

Re: tracing.rst neglects to document syntax of trace-events files

[Daniel P. Berrangé]

On Tue, Jan 18, 2022 at 09:23:50AM +0100, Markus Armbruster wrote:
> Almost[*] all trace-events files start with this line:
> 
>     # See docs/devel/tracing.rst for syntax documentation.
> 
> But I can't find syntax documentation there.

In that doc, under the heading "Declaring trace events", is a wordy
paragraph that looks like it was attempting to fill this need,
especially the last part.

[quote]
Each event declaration will start with the event name, then its arguments,
finally a format string for pretty-printing. For example::

    qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"
    qemu_vfree(void *ptr) "ptr %p"
[/quote]

It certainly has plenty of scope for improvement though !

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: tracing.rst neglects to document syntax of trace-events files

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 944 bytes --]

On Tue, Jan 18, 2022 at 09:02:35AM +0000, Daniel P. Berrangé wrote:
> On Tue, Jan 18, 2022 at 09:23:50AM +0100, Markus Armbruster wrote:
> > Almost[*] all trace-events files start with this line:
> > 
> >     # See docs/devel/tracing.rst for syntax documentation.
> > 
> > But I can't find syntax documentation there.
> 
> In that doc, under the heading "Declaring trace events", is a wordy
> paragraph that looks like it was attempting to fill this need,
> especially the last part.
> 
> [quote]
> Each event declaration will start with the event name, then its arguments,
> finally a format string for pretty-printing. For example::
> 
>     qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"
>     qemu_vfree(void *ptr) "ptr %p"
> [/quote]
> 
> It certainly has plenty of scope for improvement though !

Yes. Should we rename the "Declaring trace events" section to "Syntax
for declaring trace events"?

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]