doc: implement REUSE with SPDX identifiers

[lttng-ust.git] / doc / man / tracef-tracelog-limitations.txt

// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
// SPDX-License-Identifier: CC-BY-4.0
//
:macro-name: lttng_ust_{macro-suffix}
:vmacro-name: lttng_ust_v{macro-suffix}

The +{macro-name}()+ and +{vmacro-name}()+ utility macros were
developed to make user space tracing super simple, albeit with notable
disadvantages compared to custom, full-fledged tracepoint providers:

  * All generated events have the same provider/event names.
  * There's no static type checking.
  * The only event field with user data you actually get, named `msg`,
    is a string potentially containing the values you passed to the
    macro using your own format. This also means that you cannot use
    filtering using a custom expression at run time because there are no
    isolated fields.
  * Since +{macro-name}()+ and +{vmacro-name}()+ use C standard
    library's man:vasprintf(3) function in the background to format the
    strings at run time, their expected performance is lower than using
    custom tracepoint providers with typed fields, which do not require
    a conversion to a string.
  * Generally, a string containing the textual representation of the
    user data fields is not as compact as binary fields in the resulting
    trace.

Thus, +{macro-name}()+/+{vmacro-name}()+ are useful for quick
prototyping and debugging, but should not be considered for any
permanent/serious application instrumentation.

+{vmacro-name}()+ does not have a `STAP_PROBEV()` call, because
`STAP_PROBEV()` does not support `va_list`. If you need it, you should
emit this call yourself.

See man:lttng-ust(3) to learn more about custom tracepoint providers.