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