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 |
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 |
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 |
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 |
30 | emit this call yourself. | |
cfd56ee1 | 31 | |
4ddbd0b7 | 32 | See man:lttng-ust(3) to learn more about custom tracepoint providers. |