| 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. |