Debian Codegraph @

docs/modules/tracing-funcs/pages/index.adoc

raw
1 = Use the generated C{nbsp}tracing functions
2 :us: _
3
4 include::ROOT:partial$def-prefix-note.adoc[]
5
6 The public `barectf.h` header which barectf
7 xref:cli:index.adoc[generates] contains two groups of function
8 prototypes:
9
10 [[tracing-funcs]]Tracing functions::
11 barectf generates one tracing function per configured
12 xref:yaml:ert-obj.adoc[event record type].
13 +
14 A tracing function is named `barectf_trace{us}__DSTNAME__{us}__ERTNAME__()`,
15 where `__DSTNAME__` is the xref:yaml:dst-obj.adoc[data stream type] name
16 and `__ERTNAME__` the event record type name.
17 +
18 NOTE: If your configuration has a xref:yaml:dst-obj.adoc#is-def-prop[default
19 data stream type] named `__DEFDSTNAME__`, then barectf also generates
20 C{nbsp}preprocessor definitions named `barectf_trace{us}__ERTNAME__`
21 which are set to `barectf_trace{us}__DEFDSTNAME__{us}__ERTNAME__`.
22 +
23 Those are the functions which your application can call to write
24 xref:how-barectf-works:ctf-primer.adoc#er[CTF event records] to
25 xref:how-barectf-works:ctf-primer.adoc#ds[data streams].
26
27 Tracing control functions::
28 barectf generates the `+barectf_is_tracing_enabled()+` and
29 `+barectf_enable_tracing()+` functions to
30 <<control,control>> the tracing activity for a given
31 barectf context.
32
33 xref:platform:api.adoc[Platform API] functions::
34 barectf generates one
35 xref:platform:api.adoc#open[packet opening] and one
36 xref:platform:api.adoc#close[packet closing] function
37 per configured xref:yaml:dst-obj.adoc[data stream type].
38 +
39 It also generates a xref:platform:api.adoc#init[barectf context
40 initialization] function and a few
41 xref:platform:api.adoc#accessors[context property getters and setters].
42 +
43 The suggested barectf approach is for a
44 xref:platform:index.adoc[platform] to handle the barectf context
45 initialization, packet opening and packet closing operations.
46 +
47 This hides the details of how packets are written to the back end from
48 the application so that it only calls <<tracing-funcs,tracing>> and
49 <<control,tracing control>> functions.
50
51 [[obtain-ctx-ptr]]
52 == Obtain a barectf context pointer
53
54 <<tracing-funcs,Tracing>> and <<control,tracing control>> functions
55 accept a **_barectf context_** pointer as their first parameter.
56
57 For example:
58
59 [source,c]
60 ----
61 void barectf_my_stream_trace_my_event(struct barectf_my_stream_ctx *sctx,
62 uint8_t p_user_id, const char *p_msg);
63
64 int barectf_is_tracing_enabled(const void *vctx);
65
66 void barectf_enable_tracing(void *vctx, int enable);
67 ----
68
69 A barectf context represents a
70 xref:how-barectf-works:ctf-primer.adoc#ds[CTF data stream].
71
72 The suggested barectf approach is for a
73 xref:platform:index.adoc[platform]'s API to offer a function to obtain
74 a pointer to an initialized barectf context.
75
76 For example, the
77 https://github.com/efficios/barectf/tree/stable-{page-component-version}/platforms/linux-fs[Linux
78 FS] demonstration platform offers the
79 `+barectf_platform_linux_fs_get_barectf_ctx()+` function to obtain a
80 barectf context pointer from a platform context.
81
82 == Tracing function parameters
83
84 As explained in <<obtain-ctx-ptr>>, a tracing function's first parameter
85 is always a barectf context pointer.
86
87 The other parameters depend on the xref:yaml:index.adoc[configuration].
88
89 For a given xref:yaml:dst-obj.adoc[data stream type] and
90 xref:yaml:ert-obj.adoc[event record type], the generated tracing
91 function parameters are, in this order:
92
93 . For each member `__NAME__` of the
94 xref:yaml:dst-obj.adoc#er-common-ctx-ft-prop[event record common
95 context structure field type], a parameter named `cc{us}__NAME__`.
96
97 . For each member `__NAME__` of the
98 xref:yaml:ert-obj.adoc#spec-ctx-ft-prop[event record specific
99 context structure field type], a parameter named `sc{us}__NAME__`.
100
101 . For each member `__NAME__` of the
102 xref:yaml:ert-obj.adoc#payload-ft-prop[event record payload structure
103 field type], a parameter named `p{us}__NAME__`.
104
105 See xref:yaml:ft-obj.adoc#gen-c-types[Generated C{nbsp}types] to
106 determine the exact C{nbsp}type of each parameter.
107
108 Note that a member with a xref:yaml:dyn-array-ft-obj.adoc[dynamic array
109 field type] actually makes barectf generate _two_ adjacent parameters:
110
111 . One for the dynamic array's length.
112 +
113 Example: `uint32_t p___my_array_len`
114
115 . One for the dynamic array's data.
116 +
117 Example: `const uint8_t *p_my_array`
118
119 ====
120 Consider this xref:yaml:dst-obj.adoc[data stream type object]
121 named `my_stream`:
122
123 [source,yaml]
124 ----
125 event-record-common-context-field-type:
126 class: structure
127 members:
128 - pid: uint32
129 - t_level: double
130 event-record-types:
131 my_event:
132 specific-context-field-type:
133 class: structure
134 members:
135 - count: uint16
136 payload-field-type:
137 class: structure
138 members:
139 - msg: string
140 - src_ip_addr:
141 field-type:
142 class: static-array
143 length: 4
144 element-field-type: uint8
145 ----
146
147 The generated tracing prototype for the `my_event` event record type
148 is:
149
150 [source,c]
151 ----
152 void barectf_my_stream_trace_my_event(struct barectf_my_stream_ctx *sctx,
153 uint32_t cc_pid, double cc_t_level,
154 uint16_t sc_count, const char *p_msg,
155 const uint8_t *p_src_ip_addr);
156 ----
157 ====
158
159 [[control]]
160 == Control tracing
161
162 You can control the tracing activity for a given
163 <<obtain-ctx-ptr,barectf context>> with the following functions:
164
165 * {empty}
166 +
167 [source,c]
168 ----
169 int barectf_is_tracing_enabled(const void *vctx);
170 ----
171 +
172 Returns whether or not tracing is currenty enabled for the barectf
173 context `vctx`.
174
175 * {empty}
176 +
177 [source,c]
178 ----
179 void barectf_enable_tracing(void *vctx, int enable);
180 ----
181 +
182 Enables (if `enable` is{nbsp}1) or disables (if `enable` is{nbsp}0)
183 tracing for the barectf context `vctx`.
184
185 When tracing is disabled for a given barectf context, the
186 <<tracing-funcs,tracing functions>> have no effect for this context.
187
188 == Concurrent access safety
189
190 The C{nbsp}source code which barectf generates doesn't guarantee any
191 concurrent access safety (thread safety, reentrancy).
192
193 Because barectf generates general ANSI{nbsp}C code with no dependencies,
194 it can't know how to synchronize accesses to <<obtain-ctx-ptr,barectf
195 context>> structures. As of barectf{nbsp}{page-component-version}, you
196 need to protect tracing function calls for a given barectf context with
197 your own synchronization primitives.
198
199 Note, however, that xref:how-barectf-works:ctf-primer.adoc[CTF] is
200 designed for fast multicore/multithread tracing: dedicate one barectf
201 context (one xref:how-barectf-works:ctf-primer.adoc#ds[data stream]) per
202 core/thread to avoid tracing function locking.