2 id: using-tracepoint-classes
5 In LTTng-UST, a _tracepoint class_ is a class of tracepoints sharing the
6 same field types and names. A _tracepoint instance_ is one instance of
7 such a declared tracepoint class, with its own event name and tracepoint
10 What is documented in [Defining tracepoints](#doc-defining-tracepoints)
11 is actually how to declare a _tracepoint class_ and define a
12 _tracepoint instance_ at the same time. Without revealing the internals
13 of LTTng-UST too much, it has to be noted that one serialization
14 function is created for each tracepoint class. A serialization
15 function is responsible for serializing the fields of a tracepoint
16 into a sub-buffer when tracing. For various performance reasons, when
17 your situation requires multiple tracepoints with different names, but
18 with the same fields layout, the best practice is to manually create
19 a tracepoint class and instantiate as many tracepoint instances as
20 needed. One positive effect of such a design, amongst other advantages,
21 is that all tracepoint instances of the same tracepoint class
22 reuse the same serialization function, thus reducing cache pollution.
24 As an example, here are three tracepoint definitions as we know them:
35 ctf_integer(int, userid, userid)
36 ctf_integer(size_t, len, len)
48 ctf_integer(int, userid, userid)
49 ctf_integer(size_t, len, len)
61 ctf_integer(int, userid, userid)
62 ctf_integer(size_t, len, len)
67 In this case, three tracepoint classes are created, with one tracepoint
68 instance for each of them: `get_account`, `get_settings` and
69 `get_transaction`. However, they all share the same field names and
70 types. Declaring one tracepoint class and three tracepoint instances of
71 the latter is a better design choice:
74 /* the tracepoint class */
75 TRACEPOINT_EVENT_CLASS(
76 /* tracepoint provider name */
79 /* tracepoint class name */
90 ctf_integer(int, userid, userid)
91 ctf_integer(size_t, len, len)
95 /* the tracepoint instances */
96 TRACEPOINT_EVENT_INSTANCE(
97 /* tracepoint provider name */
100 /* tracepoint class name */
103 /* tracepoint/event name */
112 TRACEPOINT_EVENT_INSTANCE(
121 TRACEPOINT_EVENT_INSTANCE(
132 Of course, all those names and `TP_ARGS()` invocations are redundant,
133 but some C preprocessor magic can solve this:
136 #define MY_TRACEPOINT_ARGS \
142 TRACEPOINT_EVENT_CLASS(
147 ctf_integer(int, userid, userid)
148 ctf_integer(size_t, len, len)
152 #define MY_APP_TRACEPOINT_INSTANCE(name) \
153 TRACEPOINT_EVENT_INSTANCE( \
160 MY_APP_TRACEPOINT_INSTANCE(get_account)
161 MY_APP_TRACEPOINT_INSTANCE(get_settings)
162 MY_APP_TRACEPOINT_INSTANCE(get_transaction)