Convert man pages to AsciiDoc

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

diff --git a/doc/man/tracef-tracelog-limitations.txt b/doc/man/tracef-tracelog-limitations.txt
new file mode 100644 (file)
index 0000000..a949190
--- /dev/null
+++ b/doc/man/tracef-tracelog-limitations.txt
@@ -0,0 +1,24 @@
+The +{macro-name}()+ utility macro was 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}()+ uses C standard library's man:vasprintf(3)
+    function in the background to format the strings at run time, its
+    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}()+ is useful for quick prototyping and debugging, but
+should not be considered for any permanent/serious application
+instrumentation.
+
+See man:lttng-ust(3) to learn more about custom tracepoint providers.