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

: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.
Commit	Line	Data
5b1163c6 PP	1	:macro-name: lttng_ust_{macro-suffix}
	2	:vmacro-name: lttng_ust_v{macro-suffix}
	3
	4	The +{macro-name}()+ and +{vmacro-name}()+ utility macros were
45efc5a3 PP	5	developed to make user space tracing super simple, albeit with notable
45efc5a3 PP	6	disadvantages compared to custom, full-fledged tracepoint providers:
4ddbd0b7 PP	7
	8	* All generated events have the same provider/event names.
	9	* There's no static type checking.
	10	* The only event field with user data you actually get, named `msg`,
	11	is a string potentially containing the values you passed to the
	12	macro using your own format. This also means that you cannot use
	13	filtering using a custom expression at run time because there are no
	14	isolated fields.
5b1163c6	15	* Since +{macro-name}()+ and +{vmacro-name}()+ use C standard
45efc5a3 PP	16	library's man:vasprintf(3) function in the background to format the
	17	strings at run time, their expected performance is lower than using
	18	custom tracepoint providers with typed fields, which do not require
	19	a conversion to a string.
4ddbd0b7	20	* Generally, a string containing the textual representation of the
45efc5a3 PP	21	user data fields is not as compact as binary fields in the resulting
45efc5a3 PP	22	trace.
4ddbd0b7	23
5b1163c6	24	Thus, +{macro-name}()+/+{vmacro-name}()+ are useful for quick
45efc5a3 PP	25	prototyping and debugging, but should not be considered for any
45efc5a3 PP	26	permanent/serious application instrumentation.
4ddbd0b7	27
5b1163c6	28	+{vmacro-name}()+ does not have a `STAP_PROBEV()` call, because
45efc5a3 PP	29	`STAP_PROBEV()` does not support `va_list`. If you need it, you should
45efc5a3 PP	30	emit this call yourself.
cfd56ee1	31
4ddbd0b7	32	See man:lttng-ust(3) to learn more about custom tracepoint providers.