lib: remove bt_self_port{,_input,_output}
[babeltrace.git] / CONTRIBUTING.adoc
CommitLineData
cd4aac1e
PP
1// Render with Asciidoctor
2
3= Babeltrace contributor's guide
f9ded0e0 4Jérémie Galarneau, Philippe Proulx
cd4aac1e 5v0.2, 19 June 2019
beb0fb75
PP
6:toc:
7:toclevels: 5
8
beb0fb75 9
f9ded0e0
PP
10This is a partial contributor's guide for the
11http://diamon.org/babeltrace[Babeltrace] project. If you have any
cd4aac1e
PP
12questions that are not answered by this guide, please post them on
13https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[Babeltrace's
14mailing list].
15
beb0fb75 16
cd4aac1e 17== Babeltrace library
f9ded0e0 18
cd4aac1e 19=== Object reference counting and lifetime
f9ded0e0
PP
20
21This section covers the rationale behind the design of Babeltrace's
cd4aac1e
PP
22object lifetime management. This applies to the Babeltrace library, as
23well as to the CTF writer library (although the public reference
24counting functions are not named the same way).
f9ded0e0 25
cd4aac1e 26Starting from Babeltrace 2.0, all publicly exposed objects inherit a
f9ded0e0
PP
27common base: `bt_object`. This base provides a number of facilities to
28all objects, chief amongst which are lifetime management functions.
29
cd4aac1e
PP
30The lifetime of some public objects is managed by reference counting. In
31this case, the API offers the `+bt_*_get_ref()+` and `+bt_*_put_ref()+`
32functions which respectively increment and decrement an object's
33reference count.
f9ded0e0
PP
34
35As far as lifetime management in concerned, Babeltrace makes a clear
36distinction between regular objects, which have a single parent, and
37root objects, which don't.
38
39
cd4aac1e 40==== The problem
f9ded0e0
PP
41
42Let us consider a problematic case to illustrate the need for this
43distinction.
44
cd4aac1e
PP
45A user of the Babeltrace library creates a trace class, which _has_ a
46stream class (the class of a stream) and that stream class, in turn,
47_has_ an event class (the class of an event).
f9ded0e0
PP
48
49Nothing prevents this user from releasing his reference on any one of
50these objects in any order. However, all objects in the
51__trace--stream class--event class__ hierarchy can be retrieved
52from any other.
53
54For instance, the user could discard his reference on both the event
cd4aac1e
PP
55class and the stream class, only keeping a reference on the trace class.
56From this trace class reference, stream classes can be enumerated,
57providing the user with a new reference to the stream class he discarded
58earlier. Event classes can also be enumerated from stream classes,
59providing the user with references to the individual event classes.
f9ded0e0
PP
60
61Conversely, the user could also hold a reference to an event class and
cd4aac1e 62retrieve its parent stream class. The trace class, in turn, can then be
f9ded0e0
PP
63retrieved from the stream class.
64
65This example illustrates what could be interpreted as a circular
66reference dependency existing between these objects. Of course, if the
67objects in such a scenario were to hold references to each other (in
68both directions), we would be in presence of a circular ownership
69resulting in a leak of both objects as their reference counts would
70never reach zero.
71
72Nonetheless, the API must offer the guarantee that holding a node to any
73node of the graph keeps all other reachable nodes alive.
74
75
cd4aac1e 76==== The solution
f9ded0e0
PP
77
78The scheme employed in Babeltrace to break this cycle consists in the
cd4aac1e 79"children" holding _reverse component references_ to their parents. That
56e18c4c
PP
80is, in the context of the trace IR, that event classes hold a reference
81to their parent stream class and stream classes hold a reference to
cd4aac1e 82their parent trace class.
f9ded0e0 83
cd4aac1e 84On the other hand, parents hold _claiming aggregation references_ to
f9ded0e0
PP
85their children. A claiming aggregation reference means that the object
86being referenced should not be deleted as long as the reference still
87exists. In this respect, it can be said that parents truly hold the
88ownership of their children, since they control their lifetime.
89Conversely, the reference counting mechanism is leveraged by children to
90notify parents that no other child indirectly exposes the parent.
91
92When a parented object's reference count reaches zero, it invokes
cd4aac1e
PP
93`+bt_*_put_ref()+` on its parent and does _not_ free itself. However,
94from that point, the object depends on its parent to signal the moment
95when it can be safely reclaimed.
96
97The invocation of `+bt_*_put_ref()+` by the last children holding a
98reference to its parent might trigger a cascade of `+bt_*_put_ref()+`
99from child to parent. Eventually, a **root** object is reached. At that
100point, if this orphaned object's reference count reaches zero, the
101object invokes the destructor method defined by everyone of its children
102as part of their base `struct bt_object`. The key point here is that the
103cascade of destructor will necessarily originate from the root and
104propagate in preorder to the children. These children will propagate the
105destruction to their own children before reclaiming their own memory.
106This ensures that a node's pointer to its parent is _always_ valid since
107the parent has the responsibility of tearing-down their children before
108cleaning themselves up.
109
110Assuming a reference to an object is _acquired_ by calling
111`+bt_*_get_ref()+` while its reference count is zero, the object
112acquires, in turn, a reference on its parent using `+bt_*_get_ref()+`.
113At that point, the child can be thought of as having converted its weak
114reference to its parent into a regular reference. That is why this
115reference is referred to as a _claiming_ aggregation reference.
116
117
118==== Caveats
f9ded0e0
PP
119
120This scheme imposes a number of strict rules defining the relation
121between objects:
122
123* Objects may only have one parent.
124* Objects, beside the root, are only retrievable from their direct
125 parent or children.
126
127
cd4aac1e 128==== Example
f9ded0e0 129
cd4aac1e
PP
130The initial situation is rather simple: **User{nbsp}A** is holding a
131reference to a trace class, **TC1**. As per the rules previously
132enounced, stream classes **SC1** and **SC2** don't hold a reference to
133**TC1** since their own reference counts are zero. The same holds true
134for **EC1**, **EC2** and **EC3** with respect to **SC1** and **SC2**.
f9ded0e0
PP
135
136image::doc/contributing-images/bt-ref01.png[]
137
cd4aac1e
PP
138In this second step, we can see that **User{nbsp}A** has acquired a
139reference on **SC2** through the trace class, **TC1**.
f9ded0e0
PP
140
141The stream class's reference count transitions from zero to one,
142triggering the acquisition of a strong reference on **TC1** from
143**SC2**.
144
cd4aac1e
PP
145Hence, at this point, the trace class's ownership is shared by
146**User{nbsp}A** and **SC2**.
f9ded0e0
PP
147
148image::doc/contributing-images/bt-ref02.png[]
149
cd4aac1e
PP
150Next, **User{nbsp}A** acquires a reference on the **EC3** event class
151through its parent stream class, **SC2**. Again, the transition of an
152object's reference count from 0 to 1 triggers the acquisition of a
153reference on its parent.
f9ded0e0 154
cd4aac1e 155Note that SC2's reference count was incremented to 2. The trace class's
f9ded0e0
PP
156reference count remains unchanged.
157
158image::doc/contributing-images/bt-ref03.png[]
159
cd4aac1e
PP
160**User{nbsp}A** decides to drop its reference on **SC2**. **SC2**'s
161reference count returns back to 1, everything else remaining unchanged.
f9ded0e0
PP
162
163image::doc/contributing-images/bt-ref04.png[]
164
cd4aac1e
PP
165**User{nbsp}A** can then decide to drop its reference on the trace
166class. This results in a reversal of the initial situation:
167**User{nbsp}A** now owns an event, **EC3**, which is keeping everything
168else alive and reachable.
f9ded0e0
PP
169
170image::doc/contributing-images/bt-ref05.png[]
171
cd4aac1e 172If another object, **User{nbsp}B**, enters the picture and acquires a
f9ded0e0
PP
173reference on the **SC1** stream class, we see that **SC1**'s reference
174count transitioned from 0 to 1, triggering the acquisition of a
175reference on **TC1**.
176
177image::doc/contributing-images/bt-ref06.png[]
178
cd4aac1e
PP
179**User{nbsp}B** hands off a reference to **EC1**, acquired through
180**SC1**, to another object, **User{nbsp}C**. The acquisition of a
181reference on **EC1**, which transitions from 0 to 1, triggers the
182acquisition of a reference on its parent, **SC1**.
f9ded0e0
PP
183
184image::doc/contributing-images/bt-ref07.png[]
185
cd4aac1e 186At some point, **User{nbsp}A** releases its reference on **EC3**. Since
f9ded0e0
PP
187**EC3**'s reference count transitions to zero, it releases its reference
188on **SC2**. **SC2**'s reference count, in turn, reaches zero and it
189releases its reference to **TC1**.
190
191**TC1**'s reference count is now 1 and no further action is taken.
192
193image::doc/contributing-images/bt-ref08.png[]
194
cd4aac1e
PP
195**User{nbsp}B** releases its reference on **SC1**. **User{nbsp}C**
196becomes the sole owner of the whole hierarchy through his ownership of
197**EC1**.
f9ded0e0
PP
198
199image::doc/contributing-images/bt-ref09.png[]
200
cd4aac1e
PP
201Finally, **User{nbsp}C** releases his ownership of **EC1**, triggering
202the release of the whole hierarchy. Let's walk through the reclamation
203of the whole graph.
f9ded0e0 204
cd4aac1e
PP
205Mirroring what happened when **User{nbsp}A** released its last reference
206on **EC3**, the release of **EC1** by **User{nbsp}C** causes its
207reference count to fall to zero.
f9ded0e0
PP
208
209This transition to zero causes **EC1** to release its reference on
210**SC1**. **SC1**'s reference count reaching zero causes it to release
211its reference on **TC1**.
212
213image::doc/contributing-images/bt-ref10.png[]
214
215Since the reference count of **TC1**, a root object, has reached zero,
216it invokes the destructor method on its children. This method is
217recursive and causes the stream classes to call the destructor method on
218their event classes.
219
220The event classes are reached and, having no children of their own, are
221reclaimed.
222
223image::doc/contributing-images/bt-ref11.png[]
224
225The stream classes having destroyed their children, are then reclaimed
cd4aac1e 226by the trace class.
f9ded0e0
PP
227
228image::doc/contributing-images/bt-ref12.png[]
229
230Finally, the stream classes having been reclaimed, **TC1** is reclaimed.
231
232image::doc/contributing-images/bt-ref13.png[]
233
234
f9ded0e0 235== Logging
beb0fb75
PP
236
237Logging is a great instrument for a developer to be able to collect
238information about a running software.
239
240Babeltrace is a complex software with many layers. When a Babeltrace
241graph fails to run, what caused the failure? It could be caused by any
cd4aac1e
PP
242component, any message iterator, and any deeply nested validation of a
243CTF IR object (within the `ctf` plugin), for example. With the
244appropriate logging statements manually placed in the source code, we
245can find the cause of a bug faster.
beb0fb75 246
cd4aac1e
PP
247While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to
248_FATAL_ logging statements, you should liberally instrument your
ef267d12 249Babeltrace module with _TRACE_ logging statements to help future you
cd4aac1e 250and other developers understand what's happening at run time.
beb0fb75
PP
251
252
f9ded0e0 253=== Logging API
beb0fb75
PP
254
255The Babeltrace logging API is internal: it is not exposed to the users
cd4aac1e 256of the library; only to their developers. The only thing that a library
4a41523d 257user can control is the current log level of the library itself with
beb0fb75 258`bt_logging_set_global_level()` and the initial library's log level with
cd4aac1e 259the `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable.
beb0fb75
PP
260
261This API is based on https://github.com/wonder-mice/zf_log[zf_log], a
262lightweight, yet featureful, MIT-licensed core logging library for C and
cd4aac1e
PP
263pass:[C++]. The zf_log source files were modified to have the `BT_` and
264`bt_` prefixes, and other small changes, like color support and using
265the project's `BT_DEBUG_MODE` definition instead of the standard
266`NDEBUG`.
beb0fb75
PP
267
268The logging functions are implemented in the logging convenience
cd4aac1e 269library (`src/logging` directory).
beb0fb75
PP
270
271
cd4aac1e 272[[logging-headers]]
f9ded0e0 273==== Headers
beb0fb75
PP
274
275The logging API headers are:
276
3fadfbc0 277`<babeltrace2/logging.h>`::
cd4aac1e 278 Public header which a library user can use to set and get
a12f3d62 279 libbabeltrace2's current log level.
beb0fb75 280
cd4aac1e 281`"logging/log.h"`::
beb0fb75 282 Internal, generic logging API which you can use in any Babeltrace
cd4aac1e
PP
283 module. This is the translation of `zf_log.h`.
284+
285This header offers the <<gen-logging-statements,generic logging
286statement macros>>.
beb0fb75 287
cd4aac1e
PP
288`"lib/logging.h"`::
289 Specific internal header to use within the library.
290+
291This header defines `BT_LOG_OUTPUT_LEVEL` to a custom, library-wide
292hidden symbol which is the library's current log level before including
293`"logging/log.h"`.
294+
295This header offers the <<lib-logging-statements,library-specific logging
296statement macros>>.
beb0fb75 297
d9c39b0a 298`"logging/comp-logging.h"`::
cd4aac1e
PP
299 Specific internal header to use within a component class.
300+
301This header offers the <<comp-logging-statements,component-specific
302logging statement macros>>.
beb0fb75 303
b4b9064d 304
cd4aac1e 305[[log-levels]]
f9ded0e0 306==== Log levels
beb0fb75 307
cd4aac1e
PP
308The internal logging API offers the following log levels, in ascending
309order of severity:
beb0fb75 310
cd4aac1e
PP
311[options="header,autowidth",cols="4"]
312|===
313|Log level name
314|Log level short name
315|Internal API enumerator
316|Public API enumerator
317
ef267d12
PP
318|_TRACE_
319|`T`
320|`BT_LOG_TRACE`
321|`BT_LOGGING_LEVEL_TRACE`
cd4aac1e
PP
322
323|_DEBUG_
324|`D`
325|`BT_LOG_DEBUG`
326|`BT_LOGGING_LEVEL_DEBUG`
327
328|_INFO_
329|`I`
330|`BT_LOG_INFO`
331|`BT_LOGGING_LEVEL_INFO`
332
770538dd 333|_WARNING_
cd4aac1e 334|`W`
770538dd
PP
335|`BT_LOG_WARNING`
336|`BT_LOGGING_LEVEL_WARNING`
cd4aac1e
PP
337
338|_ERROR_
339|`E`
340|`BT_LOG_ERROR`
341|`BT_LOGGING_LEVEL_ERROR`
342
343|_FATAL_
344|`F`
345|`BT_LOG_FATAL`
346|`BT_LOGGING_LEVEL_FATAL`
347
348|_NONE_
349|`N`
350|`BT_LOG_NONE`
351|`BT_LOGGING_LEVEL_NONE`
352|===
353
354The short name is accepted by the log level environment variables and by
355the CLI's `--log-level` options.
beb0fb75 356
cd4aac1e 357See <<choose-a-log-level,how to decide which one to use>> below.
beb0fb75 358
cd4aac1e 359There are two important log level expressions:
beb0fb75
PP
360
361[[build-time-log-level]]Build-time, minimal log level::
cd4aac1e
PP
362 The minimal log level, or build-time log level, is set at build time
363 and determines the minimal log level of the logging statements which
364 can be executed. This applies to all the modules (CLI, library,
365 plugins, bindings, etc.).
beb0fb75
PP
366+
367All the logging statements with a level below this level are **not built
368at all**. All the logging statements with a level equal to or greater
f9ded0e0
PP
369than this level _can_ be executed, depending on the
370<<run-time-log-level,run-time log level>>.
beb0fb75
PP
371+
372You can set this level at configuration time with the
373`BABELTRACE_MINIMAL_LOG_LEVEL` environment variable, for example:
374+
375--
376----
770538dd 377$ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./configure
beb0fb75
PP
378----
379--
380+
cd4aac1e
PP
381The default build-time log level is `DEBUG`. For optimal performance,
382set it to `INFO`, which effectively disables all fast path logging in
770538dd 383all the Babeltrace modules. You can't set it to `WARNING`, `ERROR`,
dd22a91f
PP
384`FATAL`, or `NONE` because the impact on performance is minuscule
385starting from the _INFO_ log level anyway and we want any Babeltrace
386build to always be able to print _INFO_-level logs.
beb0fb75
PP
387+
388The library's public API provides `bt_logging_get_minimal_level()` to
389get the configured minimal log level.
390
391[[run-time-log-level]]Run-time, dynamic log level::
cd4aac1e
PP
392 The dynamic log level is set at run time and determines the current,
393 _active_ log level. All the logging statements with a level below
394 this level are not executed, **but they still evaluate the
395 condition**. All the logging statements with a level equal to or
396 greater than this level are executed, provided that their level is
397 also <<build-time-log-level,enabled at build time>>.
beb0fb75 398+
f9ded0e0
PP
399`zf_log` has a concept of a global run-time log level which uses the
400`_bt_log_global_output_lvl` symbol. In practice, we never use this
401symbol, and always make sure that `BT_LOG_OUTPUT_LEVEL` is defined to a
cd4aac1e
PP
402module-wise expression before including `"logging/log.h"`.
403+
404In the library, `"lib/logging.h"` defines its own
405`BT_LOG_OUTPUT_LEVEL` to the library's log level symbol before it
406includes `"logging/log.h"` itself.
beb0fb75 407+
a12f3d62 408In libbabeltrace2, the user can set the current run-time log level with
beb0fb75
PP
409the `bt_logging_set_global_level()` function, for example:
410+
411--
412[source,c]
413----
414bt_logging_set_global_level(BT_LOGGING_LEVEL_INFO);
415----
416--
417+
418The library's initial run-time log level is defined by the
cd4aac1e
PP
419`LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable, or set to _NONE_
420if this environment variable is undefined.
421+
422Other modules have their own way of setting their run-time log level.
423+
424For example, the CLI uses the `BABELTRACE_CLI_LOG_LEVEL` environment
425variable, as well as its global `--log-level` option:
426+
427----
428$ babeltrace2 --log-level=I ...
429----
430+
431The components use their own log level (as returned by
432`bt_component_get_logging_level()`). With the CLI, you can set a
433specific component's log level with its own, position-dependent
434`--log-level` option:
435+
436----
437$ babeltrace2 /path/to/trace -c sink.ctf.fs --log-level=D
438----
439+
440Code which is common to the whole project, for example `src/common`
441and `src/compat`, use function parameters to get its run-time log
442level, for example:
443+
444[source,c]
445----
446BT_HIDDEN
447char *bt_common_get_home_plugin_path(int log_level);
448----
beb0fb75 449+
cd4aac1e
PP
450Typically, when a logging-enabled module calls such a function, it
451passes its own log level expression directly (`BT_LOG_OUTPUT_LEVEL`):
beb0fb75 452+
cd4aac1e
PP
453[source,c]
454----
455path = bt_common_get_home_plugin_path(BT_LOG_OUTPUT_LEVEL);
456----
457+
458Otherwise, just pass `BT_LOG_NONE`:
459+
460----
461path = bt_common_get_home_plugin_path(BT_LOG_NONE);
462----
463
464
465[[gen-logging-statements]]
466==== Generic logging statement macros
467
468The Babeltrace logging statement macros work just like `printf()`
469(except the `+BT_LOG*_STR()+` ones) and contain their <<log-levels,log
470level>> (short name) in their name.
beb0fb75 471
cd4aac1e
PP
472Each of the following macros evaluate the
473<<build-time-log-level,build-time log level>> definition and
474<<run-time-log-level,run-time log level>> expression (as defined by
475`BT_LOG_OUTPUT_LEVEL`) to log conditionally.
beb0fb75 476
cd4aac1e
PP
477See <<logging-instrument-c-file-gen,Instrument a C source file
478(generic)>> and <<logging-instrument-h-file-gen,Instrument a C header
479file (generic)>> to learn how to be able to use the following macros.
beb0fb75 480
ef267d12
PP
481`+BT_LOGT("format string", ...)+`::
482 Generic trace logging statement.
beb0fb75 483
cd4aac1e
PP
484`+BT_LOGD("format string", ...)+`::
485 Generic debug logging statement.
beb0fb75 486
cd4aac1e
PP
487`+BT_LOGI("format string", ...)+`::
488 Generic info logging statement.
beb0fb75 489
cd4aac1e
PP
490`+BT_LOGW("format string", ...)+`::
491 Generic warning logging statement.
beb0fb75 492
cd4aac1e
PP
493`+BT_LOGE("format string", ...)+`::
494 Generic error logging statement.
beb0fb75 495
cd4aac1e
PP
496`+BT_LOGF("format string", ...)+`::
497 Generic fatal logging statement.
beb0fb75 498
ef267d12
PP
499`+BT_LOGT_STR("preformatted string")+`::
500 Generic preformatted string trace logging statement.
beb0fb75 501
cd4aac1e
PP
502`+BT_LOGD_STR("preformatted string")+`::
503 Generic preformatted string debug logging statement.
beb0fb75 504
cd4aac1e
PP
505`+BT_LOGI_STR("preformatted string")+`::
506 Generic preformatted string info logging statement.
beb0fb75 507
cd4aac1e
PP
508`+BT_LOGW_STR("preformatted string")+`::
509 Generic preformatted string warning logging statement.
beb0fb75 510
cd4aac1e
PP
511`+BT_LOGE_STR("preformatted string")+`::
512 Generic preformatted string error logging statement.
beb0fb75 513
cd4aac1e
PP
514`+BT_LOGF_STR("preformatted string")+`::
515 Generic preformatted string fatal logging statement.
beb0fb75 516
ef267d12
PP
517`+BT_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
518 Generic memory trace logging statement.
beb0fb75 519
cd4aac1e
PP
520`+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
521 Generic memory debug logging statement.
b81626f9 522
cd4aac1e
PP
523`+BT_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
524 Generic memory info logging statement.
b81626f9 525
cd4aac1e
PP
526`+BT_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
527 Generic memory warning logging statement.
b81626f9 528
cd4aac1e
PP
529`+BT_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
530 Generic memory error logging statement.
b81626f9 531
cd4aac1e
PP
532`+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
533 Generic memory fatal logging statement.
b81626f9 534
ef267d12
PP
535`+BT_LOGT_ERRNO("initial message", "format string", ...)+`::
536 Generic `errno` string trace logging statement.
b81626f9 537
cd4aac1e
PP
538`+BT_LOGD_ERRNO("initial message", "format string", ...)+`::
539 Generic `errno` string debug logging statement.
beb0fb75 540
cd4aac1e
PP
541`+BT_LOGI_ERRNO("initial message", "format string", ...)+`::
542 Generic `errno` string info logging statement.
beb0fb75 543
cd4aac1e
PP
544`+BT_LOGW_ERRNO("initial message", "format string", ...)+`::
545 Generic `errno` string warning logging statement.
beb0fb75 546
cd4aac1e
PP
547`+BT_LOGE_ERRNO("initial message", "format string", ...)+`::
548 Generic `errno` string error logging statement.
beb0fb75 549
cd4aac1e
PP
550`+BT_LOGF_ERRNO("initial message", "format string", ...)+`::
551 Generic `errno` string fatal logging statement.
beb0fb75 552
cd4aac1e
PP
553
554[[lib-logging-statements]]
555==== Library-specific logging statement macros
556
557The Babeltrace library contains an internal logging API based on the
558generic logging framework. You can use it to log known Babeltrace
559objects without having to manually log each member.
560
561See <<logging-instrument-c-file-lib,Instrument a library C source file>>
562and <<logging-instrument-h-file-lib,Instrument a library C header file>> to
563learn how to be able to use the following macros.
564
565The library logging statement macros are named `+BT_LIB_LOG*()+` instead
566of `+BT_LOG*()+`:
567
ef267d12
PP
568`+BT_LIB_LOGT("format string", ...)+`::
569 Library trace logging statement.
cd4aac1e
PP
570
571`+BT_LIB_LOGD("format string", ...)+`::
572 Library debug logging statement.
573
574`+BT_LIB_LOGI("format string", ...)+`::
575 Library info logging statement.
576
577`+BT_LIB_LOGW("format string", ...)+`::
578 Library warning logging statement.
579
580`+BT_LIB_LOGE("format string", ...)+`::
581 Library error logging statement.
582
583`+BT_LIB_LOGF("format string", ...)+`::
584 Library fatal logging statement.
585
3cd4c495
PP
586`+BT_LIB_LOGW_APPEND_CAUSE("format string", ...)+`::
587 Library warning logging statement, and unconditional error cause
588 appending.
589
590`+BT_LIB_LOGE_APPEND_CAUSE("format string", ...)+`::
591 Library error logging statement, and unconditional error cause
592 appending.
593
594`+BT_LIB_LOGF_APPEND_CAUSE("format string", ...)+`::
595 Library fatal logging statement, and unconditional error cause
596 appending.
597
cd4aac1e
PP
598The macros above accept the typical `printf()` conversion specifiers
599with the following limitations:
600
601* The `+*+` width specifier is not accepted.
602* The `+*+` precision specifier is not accepted.
603* The `j` and `t` length modifiers are not accepted.
604* The `n` format specifier is not accepted.
605* The format specifiers defined in `<inttypes.h>` are not accepted,
606 except for `PRId64`, `PRIu64`, `PRIx64`, `PRIX64`, `PRIo64`, and
607 `PRIi64`.
608
609The Babeltrace library custom conversion specifier is accepted. Its
610syntax is either `%!u` to format a UUID (`bt_uuid` type), or:
611
612. Introductory `%!` sequence.
613
614. **Optional**: `[` followed by a custom prefix for the printed fields
615 of this specifier, followed by `]`. The standard form is to end this
616 prefix with `-` so that, for example, with the prefix `tc-`, the
617 complete field name becomes `tc-addr`.
618
619. **Optional**: `pass:[+]` to print extended object members. This
620 depends on the provided format specifier.
621
622. Format specifier (see below).
623
624The available format specifiers are:
625
626[options="header,autowidth",cols="3"]
627|===
628|Specifier
629|Object
630|Expected C type
631
632|`F`
633|Trace IR field class
6769570a 634|`+const struct bt_field_class *+`
cd4aac1e
PP
635
636|`f`
637|Trace IR field
6769570a 638|`+const struct bt_field *+`
cd4aac1e
PP
639
640|`P`
641|Trace IR field path
6769570a 642|`+const struct bt_field_path *+`
cd4aac1e
PP
643
644|`E`
645|Trace IR event class
6769570a 646|`+const struct bt_event_class *+`
cd4aac1e
PP
647
648|`e`
649|Trace IR event
6769570a 650|`+const struct bt_event *+`
cd4aac1e
PP
651
652|`S`
653|Trace IR stream class.
6769570a 654|`+const struct bt_stream_class *+`
cd4aac1e
PP
655
656|`s`
657|Trace IR stream
6769570a 658|`+const struct bt_stream *+`
cd4aac1e
PP
659
660|`a`
661|Trace IR packet
6769570a 662|`+const struct bt_packet *+`
cd4aac1e
PP
663
664|`T`
665|Trace IR trace class
6769570a 666|`+const struct bt_trace_class *+`
cd4aac1e
PP
667
668|`t`
669|Trace IR trace
6769570a 670|`+const struct bt_trace *+`
cd4aac1e
PP
671
672|`K`
673|Trace IR clock class
6769570a 674|`+const struct bt_clock_class *+`
cd4aac1e
PP
675
676|`k`
677|Trace IR clock snapshot
6769570a 678|`+const struct bt_clock_snapshot *+`
cd4aac1e
PP
679
680|`v`
681|Value object
6769570a
PP
682|`+const struct bt_value *+`
683
684|`R`
685|Integer range set
686|`const struct bt_integer_range_set *`
cd4aac1e
PP
687
688|`n`
689|Message
6769570a 690|`+const struct bt_message *+`
cd4aac1e
PP
691
692|`i`
693|Message iterator
694|`struct bt_message_iterator *`
695
696|`C`
697|Component class
698|`struct bt_component_class *`
699
700|`c`
701|Component
6769570a 702|`+const struct bt_component *+`
cd4aac1e
PP
703
704|`p`
705|Port
6769570a 706|`+const struct bt_port *+`
cd4aac1e
PP
707
708|`x`
709|Connection
6769570a 710|`+const struct bt_connection *+`
cd4aac1e
PP
711
712|`g`
713|Graph
6769570a 714|`+const struct bt_graph *+`
cd4aac1e 715
b70d57a1
PP
716|`z`
717|Interrupter
718|`+struct bt_interrupter *+`
719
cd4aac1e
PP
720|`l`
721|Plugin
6769570a 722|`+const struct bt_plugin *+`
cd4aac1e 723
553c4bab
PP
724|`r`
725|Error cause
6769570a 726|`+const struct bt_error_cause *+`
553c4bab 727
cd4aac1e
PP
728|`o`
729|Object pool
6769570a 730|`+const struct bt_object_pool *+`
cd4aac1e
PP
731
732|`O`
733|Object
6769570a 734|`+const struct bt_object *+`
cd4aac1e
PP
735|===
736
737Conversion specifier examples:
738
739* `%!f`
740* `%![my-event-]+e`
741* `%!t`
742* `%!+F`
743
744The ``, `` string (comma and space) is printed between individual
745fields, but **not after the last one**. Therefore, you must put this
746separator in the format string between two conversion specifiers, for
747example:
748
749[source,c]
750----
751BT_LIB_LOGW("Message: count=%u, %!E, %!+K", count, event_class, clock_class);
752----
753
754Example with a custom prefix:
755
756[source,c]
757----
758BT_LIB_LOGI("Some message: %![ec-a-]e, %![ec-b-]+e", ec_a, ec_b);
759----
760
761It is safe to pass `NULL` as any Babeltrace object parameter: the macros
762only print its null address.
763
764WARNING: Build-time `printf()` format checks are disabled for the
765`+BT_LIB_LOG*()+` macros because there are custom conversion specifiers,
766so make sure to test your logging statements.
767
768
769[[comp-logging-statements]]
770==== Component-specific logging statement macros
771
772There are available logging macros for components. They prepend a prefix
773including the component's name to the logging message.
774
775See <<logging-instrument-c-file-compcls,Instrument a component class C
776source file>> and <<logging-instrument-h-file-compcls,Instrument a
777component class C header file>> to learn how to be able to use the
778following macros.
779
780The component logging statement macros are named `+BT_COMP_LOG*()+`
781instead of `+BT_LOG*()+`:
782
ef267d12
PP
783`+BT_COMP_LOGT("format string", ...)+`::
784 Component trace logging statement.
cd4aac1e
PP
785
786`+BT_COMP_LOGD("format string", ...)+`::
787 Component debug logging statement.
788
789`+BT_COMP_LOGI("format string", ...)+`::
790 Component info logging statement.
791
792`+BT_COMP_LOGW("format string", ...)+`::
793 Component warning logging statement.
794
795`+BT_COMP_LOGE("format string", ...)+`::
796 Component error logging statement.
797
798`+BT_COMP_LOGF("format string", ...)+`::
799 Component fatal logging statement.
800
ef267d12
PP
801`+BT_COMP_LOGT_STR("preformatted string")+`::
802 Component preformatted string trace logging statement.
cd4aac1e
PP
803
804`+BT_COMP_LOGD_STR("preformatted string")+`::
805 Component preformatted string debug logging statement.
806
807`+BT_COMP_LOGI_STR("preformatted string")+`::
808 Component preformatted string info logging statement.
809
810`+BT_COMP_LOGW_STR("preformatted string")+`::
811 Component preformatted string warning logging statement.
812
813`+BT_COMP_LOGE_STR("preformatted string")+`::
814 Component preformatted string error logging statement.
815
816`+BT_COMP_LOGF_STR("preformatted string")+`::
817 Component preformatted string fatal logging statement.
818
ef267d12
PP
819`+BT_COMP_LOGT_ERRNO("initial message", "format string", ...)+`::
820 Component `errno` string trace logging statement.
cd4aac1e
PP
821
822`+BT_COMP_LOGD_ERRNO("initial message", "format string", ...)+`::
823 Component `errno` string debug logging statement.
824
825`+BT_COMP_LOGI_ERRNO("initial message", "format string", ...)+`::
826 Component `errno` string info logging statement.
827
828`+BT_COMP_LOGW_ERRNO("initial message", "format string", ...)+`::
829 Component `errno` string warning logging statement.
830
831`+BT_COMP_LOGE_ERRNO("initial message", "format string", ...)+`::
832 Component `errno` string error logging statement.
833
834`+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`::
835 Component `errno` string fatal logging statement.
836
ef267d12
PP
837`+BT_COMP_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
838 Component memory trace logging statement.
cd4aac1e
PP
839
840`+BT_COMP_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
841 Component memory debug logging statement.
842
843`+BT_COMP_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
844 Component memory info logging statement.
845
846`+BT_COMP_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
847 Component memory warning logging statement.
848
849`+BT_COMP_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
850 Component memory error logging statement.
851
852`+BT_COMP_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
853 Component memory fatal logging statement.
beb0fb75
PP
854
855
f9ded0e0 856==== Conditional logging
beb0fb75 857
cd4aac1e 858`+BT_LOG_IF(cond, statement)+`::
beb0fb75
PP
859 Execute `statement` only if `cond` is true.
860+
861Example:
862+
863--
864[source,c]
865----
866BT_LOG_IF(i < count / 2, BT_LOGD("Log this: i=%d", i));
867----
868--
869
870To check the <<build-time-log-level,build-time log level>>:
871
872[source,c]
873----
874#if BT_LOG_ENABLED_DEBUG
875...
876#endif
877----
878
cd4aac1e
PP
879This tests if the _DEBUG_ level was enabled at build time. This means
880that the current, <<run-time-log-level,run-time log level>> _could_ be
f9ded0e0
PP
881_DEBUG_, but it could also be higher. The rule of thumb is to use only
882logging statements at the same level in a `BT_LOG_ENABLED_*` conditional
883block.
beb0fb75
PP
884
885The available definitions for build-time conditions are:
886
ef267d12 887* `BT_LOG_ENABLED_TRACE`
beb0fb75
PP
888* `BT_LOG_ENABLED_DEBUG`
889* `BT_LOG_ENABLED_INFO`
770538dd 890* `BT_LOG_ENABLED_WARNING`
beb0fb75
PP
891* `BT_LOG_ENABLED_ERROR`
892* `BT_LOG_ENABLED_FATAL`
893
894To check the current, <<run-time-log-level,run-time log level>>:
895
896[source,c]
897----
898if (BT_LOG_ON_DEBUG) {
899 ...
900}
901----
902
903This tests if the _DEBUG_ log level is dynamically turned on
cd4aac1e 904(implies that it's also enabled at build time). This check could have a
beb0fb75
PP
905noticeable impact on performance.
906
907The available definitions for run-time conditions are:
908
ef267d12 909* `BT_LOG_ON_TRACE`
beb0fb75
PP
910* `BT_LOG_ON_DEBUG`
911* `BT_LOG_ON_INFO`
770538dd 912* `BT_LOG_ON_WARNING`
beb0fb75
PP
913* `BT_LOG_ON_ERROR`
914* `BT_LOG_ON_FATAL`
915
cd4aac1e
PP
916Those macros check the module-specific log level symbol (defined by
917`BT_LOG_OUTPUT_LEVEL`).
beb0fb75
PP
918
919Never, ever write code which would be executed only to compute the
920fields of a logging statement outside a conditional logging scope,
921for example:
922
923[source,c]
924----
925int number = get_number_of_event_classes_with_property_x(...);
926BT_LOGD("Bla bla: number=%d", number);
927----
928
929Do this instead:
930
931[source,c]
932----
933if (BT_LOG_ON_DEBUG) {
934 int number = get_number_of_event_classes_with_property_x(...);
935 BT_LOGD("Bla bla: number=%d", number);
936}
937----
938
939Or even this:
940
941[source,c]
942----
943BT_LOGD("Bla bla: number=%d", get_number_of_event_classes_with_property_x(...));
944----
945
946
cd4aac1e 947=== Guides
beb0fb75 948
cd4aac1e
PP
949[[logging-instrument-c-file-gen]]
950==== Instrument a C source file (generic)
beb0fb75 951
cd4aac1e
PP
952To instrument a C source file (`.c`):
953
954. At the top of the file, before the first `#include` line (if any),
955 define your file's <<choose-a-logging-tag,logging tag>> name:
4a41523d
PP
956+
957--
958[source,c]
959----
cd4aac1e 960#define BT_LOG_TAG "SUBSYS/MY-MODULE/MY-FILE"
4a41523d
PP
961----
962--
cd4aac1e
PP
963
964. Below the line above, define the source file's log level expression,
965 `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
966 <<gen-logging-statements,logging statement>> to know the current
967 <<run-time-log-level,run-time log level>>.
968+
969Examples:
970+
971[source,c]
972----
973/* Global log level variable */
974#define BT_LOG_OUTPUT_LEVEL module_global_log_level
975----
4a41523d 976+
cd4aac1e
PP
977[source,c]
978----
979/* Local log level variable; must exist where you use BT_LOG*() */
980#define BT_LOG_OUTPUT_LEVEL log_level
981----
982+
983[source,c]
984----
985/* Object's log level; `obj` must exist where you use BT_LOG*() */
986#define BT_LOG_OUTPUT_LEVEL (obj->log_level)
987----
4a41523d 988
cd4aac1e 989. Include `"logging/log.h"`:
4a41523d 990+
beb0fb75
PP
991[source,c]
992----
578e048b 993#include "logging/log.h"
cd4aac1e 994----
4a41523d 995
cd4aac1e
PP
996. In the file, instrument your code with the
997 <<gen-logging-statements,generic logging statement macros>>.
4a41523d 998
cd4aac1e
PP
999
1000[[logging-instrument-h-file-gen]]
1001==== Instrument a C header file (generic)
1002
1003To instrument a C header file (`.h`), if you have `static inline`
1004functions in it:
1005
1006. Do not include `"logging/log.h"`!
1007
1008. Do one of:
1009
1010.. In the file, instrument your code with the
1011 <<gen-logging-statements,generic logging statement macros>>, making
1012 each of them conditional to the existence of the macro you're using:
4a41523d 1013+
cd4aac1e
PP
1014[source,c]
1015----
1016static inline
1017int some_function(int x)
1018{
1019 /* ... */
4a41523d 1020
ef267d12
PP
1021#ifdef BT_LOGT
1022 BT_LOGT(...);
cd4aac1e 1023#endif
beb0fb75 1024
cd4aac1e 1025 /* ... */
6470c171 1026
cd4aac1e
PP
1027#ifdef BT_LOGW_STR
1028 BT_LOGW_STR(...);
1029#endif
f9ded0e0 1030
cd4aac1e
PP
1031 /* ... */
1032}
1033----
1034+
1035The C source files which include this header file determine if logging
1036is enabled or not for them, and if so, what is their
1037<<choose-a-logging-tag,logging tag>> and <<run-time-log-level,run-time
1038log level>> expression.
f9ded0e0 1039
cd4aac1e
PP
1040.. Require that logging be enabled:
1041+
1042[source,c]
1043----
1044/* Protection: this file uses BT_LOG*() macros directly */
1045#ifndef BT_LOG_SUPPORTED
1046# error Please include "logging/log.h" before including this file.
1047#endif
1048----
1049+
1050Then, in the file, instrument your code with the
1051<<gen-logging-statements,generic logging statement macros>>.
1052
1053
1054[[logging-instrument-c-file-lib]]
1055==== Instrument a library C source file
1056
1057To instrument a library C source file (`.c`):
4a41523d
PP
1058
1059. At the top of the file, before the first `#include` line (if any),
cd4aac1e
PP
1060 define your file's <<choose-a-logging-tag,logging tag>> name (this
1061 tag must start with `LIB/`):
4a41523d
PP
1062+
1063--
1064[source,c]
1065----
cd4aac1e 1066#define BT_LOG_TAG "LIB/THE-FILE"
4a41523d
PP
1067----
1068--
cd4aac1e
PP
1069
1070. Include `"lib/logging.h"`:
4a41523d 1071+
cd4aac1e
PP
1072[source,c]
1073----
1074#include "lib/logging.h"
1075----
4a41523d 1076
cd4aac1e
PP
1077. In the file, instrument your code with the
1078 <<lib-logging-statements,library logging statement macros>> or with
1079 the <<gen-logging-statements,generic logging statement macros>>.
4a41523d 1080
f9ded0e0 1081
cd4aac1e
PP
1082[[logging-instrument-h-file-lib]]
1083==== Instrument a library C header file
1084
1085To instrument a library C header file (`.h`), if you have `static
1086inline` functions in it:
1087
1088. Do not include `"lib/logging.h"`!
1089
1090. Require that library logging be enabled:
1091+
1092[source,c]
1093----
1094/* Protection: this file uses BT_LIB_LOG*() macros directly */
1095#ifndef BT_LIB_LOG_SUPPORTED
1096# error Please include "lib/logging.h" before including this file.
1097#endif
1098----
1099
1100. In the file, instrument your code with the
1101 <<lib-logging-statements,library logging statement macros>> or with
1102 the <<gen-logging-statements,generic logging statement macros>>.
f9ded0e0 1103
4a41523d 1104
cd4aac1e
PP
1105[[logging-instrument-c-file-compcls]]
1106==== Instrument a component class C source file
1107
1108To instrument a component class C source file (`.c`):
1109
1110. At the top of the file, before the first `#include` line (if any),
1111 define your file's <<choose-a-logging-tag,logging tag>> name (this tag
1112 must start with `PLUGIN/` followed by the component class identifier):
4a41523d
PP
1113+
1114--
1115[source,c]
1116----
cd4aac1e
PP
1117#define BT_LOG_TAG "PLUGIN/SRC.MY-PLUGIN.MY-SRC"
1118----
1119--
4a41523d 1120
cd4aac1e
PP
1121. Below the line above, define the source file's log level expression,
1122 `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
1123 <<comp-logging-statements,logging statement>> to know the current
1124 <<run-time-log-level,run-time log level>>.
1125+
1126For a component class file, it is usually a member of a local component
1127private structure variable:
1128+
1129[source,c]
1130----
1131#define BT_LOG_OUTPUT_LEVEL (my_comp->log_level)
1132----
4a41523d 1133
cd4aac1e
PP
1134. Below the line above, define `BT_COMP_LOG_SELF_COMP` to an expression
1135 which, evaluated in the context of the
1136 <<comp-logging-statements,logging statements>>, evaluates to the self
1137 component address (`+bt_self_component *+`) of the component.
1138+
1139This is usually a member of a local component private structure
1140variable:
1141+
1142[source,c]
1143----
1144#define BT_COMP_LOG_SELF_COMP (my_comp->self_comp)
1145----
1146
d9c39b0a 1147. Include `"logging/comp-logging.h"`:
cd4aac1e
PP
1148+
1149[source,c]
1150----
d9c39b0a 1151#include "logging/comp-logging.h"
cd4aac1e
PP
1152----
1153
1154. In the component initialization method, make sure to set the
1155 component private structure's log level member to the initial
1156 component's log level:
1157+
1158[source,c]
1159----
1160struct my_comp {
1161 bt_logging_level log_level;
4a41523d 1162 /* ... */
cd4aac1e 1163};
4a41523d 1164
cd4aac1e
PP
1165BT_HIDDEN
1166bt_self_component_status my_comp_init(
1167 bt_self_component_source *self_comp_src,
1168 bt_value *params, void *init_method_data)
1169{
1170 struct my_comp *my_comp = g_new0(struct my_comp, 1);
1171 bt_self_component *self_comp =
1172 bt_self_component_source_as_self_component(self_comp_src);
1173 const bt_component *comp = bt_self_component_as_component(self_comp);
1174
1175 BT_ASSERT(my_comp);
1176 my_comp->log_level = bt_component_get_logging_level(comp);
4a41523d
PP
1177
1178 /* ... */
1179}
1180----
cd4aac1e
PP
1181
1182. In the file, instrument your code with the
1183 <<comp-logging-statements,component logging statement macros>>.
1184
1185
1186[[logging-instrument-h-file-compcls]]
1187==== Instrument a component class C header file
1188
1189To instrument a component class C header file (`.h`), if you have
1190`static inline` functions in it:
1191
d9c39b0a 1192. Do not include `"logging/comp-logging.h"`!
cd4aac1e
PP
1193
1194. Require that component logging be enabled:
4a41523d 1195+
cd4aac1e
PP
1196[source,c]
1197----
1198/* Protection: this file uses BT_COMP_LOG*() macros directly */
1199#ifndef BT_COMP_LOG_SUPPORTED
d9c39b0a 1200# error Please include "logging/comp-logging.h" before including this file.
cd4aac1e
PP
1201#endif
1202----
1203
1204. In the file, instrument your code with the
1205 <<comp-logging-statements,component logging statement macros>>.
1206
1207
1208[[choose-a-logging-tag]]
1209==== Choose a logging tag
beb0fb75 1210
cd4aac1e
PP
1211Each logging-enabled C source file must define `BT_LOG_TAG` to a logging
1212tag. A logging tag is a namespace to identify the logging messages of
1213this specific source file.
beb0fb75 1214
cd4aac1e
PP
1215In general, a logging tag name _must_ be only uppercase letters, digits,
1216and the `-`, `.`, and `/` characters.
beb0fb75 1217
cd4aac1e
PP
1218Use `/` to show the subsystem to source file hierarchy.
1219
1220For the Babeltrace library, start with `LIB/`.
1221
1222For the CTF writer library, start with `CTF-WRITER/`.
1223
1224For component classes, use:
beb0fb75 1225
93841983 1226[verse]
cd4aac1e
PP
1227`PLUGIN/__CCTYPE__.__PNAME__.__CCNAME__[/__FILE__]`
1228
1229With:
1230
1231`__CCTYPE__`::
1232 Component class's type (`SRC`, `FLT`, or `SINK`).
beb0fb75 1233
cd4aac1e 1234`__PNAME__`::
93841983 1235 Plugin's name.
beb0fb75 1236
cd4aac1e 1237`__CCNAME__`::
93841983 1238 Component class's name.
beb0fb75 1239
cd4aac1e 1240`__FILE__`::
93841983 1241 Additional information to specify the source file name or module.
beb0fb75 1242
cd4aac1e 1243For plugins (files common to many component classes), use:
beb0fb75 1244
cd4aac1e
PP
1245[verse]
1246`PLUGIN/__PNAME__[/__FILE__]`
beb0fb75 1247
cd4aac1e 1248With:
beb0fb75 1249
cd4aac1e
PP
1250`__PNAME__`::
1251 Plugin's name.
1252
1253`__FILE__`::
1254 Additional information to specify the source file name or module.
1255
1256
1257[[choose-a-log-level]]
1258==== Choose a log level
beb0fb75
PP
1259
1260Choosing the appropriate level for your logging statement is very
1261important.
1262
cd4aac1e 1263[options="header,autowidth",cols="1,2,3a,4"]
beb0fb75 1264|===
cd4aac1e 1265|Log level |Description |Use cases |Expected impact on performance
beb0fb75
PP
1266
1267|_FATAL_
cd4aac1e
PP
1268|
1269The program, library, or plugin cannot continue to work in this
beb0fb75
PP
1270condition: it must be terminated immediately.
1271
b4b9064d 1272A _FATAL_-level logging statement should always be followed by
4a41523d 1273`abort()`.
beb0fb75
PP
1274|
1275* Unexpected return values from system calls.
4a41523d
PP
1276* Logic error in internal code, for example an unexpected value in a
1277 `switch` statement.
cd4aac1e 1278* Failed assertion (within `BT_ASSERT()`).
bdb288b3
PP
1279* Unsatisfied library precondition (within `BT_ASSERT_PRE()` or
1280 `BT_ASSERT_PRE_DEV()`).
1281* Unsatisfied library postcondition (within `BT_ASSERT_POST()` or
1282 `BT_ASSERT_POST_DEV()`).
dd22a91f 1283|Almost none: always enabled.
beb0fb75
PP
1284
1285|_ERROR_
cd4aac1e
PP
1286|
1287An important error which is somewhat not fatal, that is, the program,
beb0fb75
PP
1288library, or plugin can continue to work after this, but you judge that
1289it should be reported to the user.
1290
1291Usually, the program cannot recover from such an error, but it can at
1292least exit cleanly.
1293|
1294* Memory allocation errors.
cd4aac1e
PP
1295* Wrong component initialization parameters.
1296* Corrupted, unrecoverable trace data.
beb0fb75
PP
1297* Failed to perform an operation which should work considering the
1298 implementation and the satisfied preconditions. For example, the
1299 failure to create an empty object (no parameters): most probably
1300 failed internally because of an allocation error.
93841983 1301* Almost any error in terminal elements: CLI and plugins.
dd22a91f 1302|Almost none: always enabled.
beb0fb75 1303
770538dd 1304|_WARNING_
cd4aac1e
PP
1305|
1306An error which still allows the execution to continue, but you judge
1307that it should be reported to the user.
6c1b33a8 1308
770538dd
PP
1309_WARNING_-level logging statements are for any error or weird action
1310that is directly or indirectly caused by the user, often through some
1311bad input data. For example, not having enough memory is considered
1312beyond the user's control, so we always log memory errors with an
1313_ERROR_ level (not _FATAL_ because we usually don't abort in this
1314condition).
beb0fb75 1315|
cd4aac1e
PP
1316* Missing data within something that is expected to have it, but there's
1317 an alternative.
1318* Invalid file, but recoverable/fixable.
dd22a91f 1319|Almost none: always enabled.
beb0fb75
PP
1320
1321|_INFO_
beb0fb75 1322|
cd4aac1e
PP
1323Any useful information which a non-developer user would possibly
1324understand.
1325
1326Anything logged with this level must _not_ happen repetitively on the
1327fast path, that is, nothing related to each message, for example. This
1328level is used for sporadic and one-shot events.
1329|
1330* CLI or component configuration report.
1331* Successful plugin, component, or message iterator initialization.
1332* In the library: anything related to plugins, graphs, component
1333 classes, components, message iterators, connections, and ports which
1334 is not on the fast path.
beb0fb75 1335* Successful connection to or disconnection from another system.
4a41523d 1336* An _optional_ subsystem cannot be loaded.
cd4aac1e
PP
1337* An _optional_ field/datum cannot be found.
1338|
dd22a91f 1339Very little: always enabled.
beb0fb75
PP
1340
1341|_DEBUG_
beb0fb75 1342|
cd4aac1e
PP
1343Something that only Babeltrace developers would be interested into,
1344which can occur on the fast path, but not more often than once per
1345message.
1346
1347The _DEBUG_ level is the default <<build-time-log-level,build-time log
1348level>> as, since it's not _too_ verbose, the performance is similar to
1349an _INFO_ build.
1350|
1351* Object construction and destruction.
1352* Object recycling (except fields).
1353* Object copying (except fields and values).
1354* Object freezing (whatever the type, as freezing only occurs in
1355 developer mode).
9b4f9b42 1356* Object interruption.
cd4aac1e
PP
1357* Calling user methods and logging the result.
1358* Setting object properties (except fields and values).
1359|
ef267d12 1360Noticeable, but not as much as the _TRACE_ level: could be executed
cd4aac1e
PP
1361in production if you're going to need a thorough log for support
1362tickets without having to rebuild the project.
beb0fb75 1363
ef267d12 1364|_TRACE_
cd4aac1e
PP
1365|
1366Low-level debugging context information (anything that does not fit the
1367other log levels). More appropriate for tracing in general.
beb0fb75
PP
1368|
1369* Reference count change.
cd4aac1e 1370* Fast path, low level state machine's state change.
beb0fb75
PP
1371* Get or set an object's property.
1372* Object comparison's intermediate results.
1373|Huge: not executed in production.
1374|===
1375
cd4aac1e
PP
1376[IMPORTANT]
1377--
770538dd 1378Make sure not to use a _WARNING_ (or higher) log level when the
cd4aac1e
PP
1379condition leading to the logging statement can occur under normal
1380circumstances.
1381
1382For example, a public function to get some object or
1383property from an object by name or key that fails to find the value is
1384not a warning scenario: the user could legitimately use this function to
1385check if the name/key exists in the object. In this case, use the
ef267d12 1386_TRACE_ level (or do not log at all).
cd4aac1e 1387--
b4b9064d 1388
beb0fb75 1389
b4b9064d 1390[[message]]
cd4aac1e 1391==== Write an appropriate message
beb0fb75
PP
1392
1393Follow those rules when you write a logging statement's message:
1394
cd4aac1e
PP
1395* Use an English sentence which starts with a capital letter.
1396
1397* Start the sentence with the appropriate verb tense depending on the
1398 context. For example:
beb0fb75
PP
1399+
1400--
b4b9064d
PP
1401** Beginning of operation (present continuous): _Creating ..._,
1402 _Copying ..._, _Serializing ..._, _Freezing ..._, _Destroying ..._
1403** End of operation (simple past): _Created ..._, _Successfully created ..._,
1404 _Failed to create ..._, _Set ..._ (simple past of _to set_ which is
1405 also _set_)
beb0fb75
PP
1406--
1407+
1408For warning and error messages, you can start the message with _Cannot_
b4b9064d 1409or _Failed to_ followed by a verb if it's appropriate.
beb0fb75
PP
1410
1411* Do not include the log level in the message itself. For example,
1412 do not start the message with _Error while_ or _Warning:_.
1413
cd4aac1e
PP
1414* Do not put newlines, tabs, or other special characters in the message,
1415 unless you want to log a string with such characters. Note that
1416 multiline logging messages can be hard to parse, analyze, and filter,
1417 however, so prefer multiple logging statements over a single statement
1418 with newlines.
beb0fb75
PP
1419
1420* **If there are fields that your logging statement must record**,
1421 follow the message with `:` followed by a space, then with the list of
1422 fields (more about this below). If there are no fields, end the
1423 sentence with a period.
1424
1425The statement's fields _must_ be a comma-separated list of
cd4aac1e
PP
1426`__name__=__value__` tokens. Keep `__name__` as simple as possible; use
1427kebab case if possible. If `__value__` is a non-alphanumeric string, put
1428it between double quotes (`"%s"` specifier). Always use the `PRId64` and
1429`PRIu64` specifiers to log an `int64_t` or an `uint64_t` value. Use `%d`
1430to log a boolean value.
beb0fb75
PP
1431
1432Example:
1433
cd4aac1e
PP
1434 "Cannot read stream data for indexing: path=\"%s\", name=\"%s\", "
1435 "stream-id=%" PRIu64 ", stream-fd=%d, "
1436 "index=%" PRIu64 ", status=%s, is-mapped=%d"
beb0fb75 1437
cd4aac1e
PP
1438By following a standard format for the statement fields, it is easier to
1439use tools like https://www.elastic.co/products/logstash[Logstash] or
1440even https://www.splunk.com/[Splunk] to split fields and analyze logs.
beb0fb75
PP
1441
1442Prefer the following suffixes in field names:
1443
1444[options="header,autowidth"]
1445|===
1446|Field name suffix |Description |Format specifier
1447
1448|`-addr` |Memory address |`%p`
1449|`-fd` |File descriptor |`%d`
cd4aac1e
PP
1450|`-fp` |File stream (`+FILE *+`) |`%p`
1451|`-id` |Object's ID |`%" PRIu64 "`
1452|`-index` |Index |`%" PRIu64 "`
beb0fb75 1453|`-name` |Object's name |`\"%s\"`
beb0fb75
PP
1454|===
1455
1456
f9ded0e0 1457=== Output
beb0fb75
PP
1458
1459The log is printed to the standard error stream. A log line contains the
cd4aac1e
PP
1460time, the process and thread IDs, the <<log-levels,log level>>, the
1461<<choose-a-logging-tag,logging tag>>, the source's function name, file
1462name and line number, and the <<message,message>>.
beb0fb75 1463
f9ded0e0
PP
1464When Babeltrace supports terminal color codes (depends on the
1465`BABELTRACE_TERM_COLOR` environment variable's value and what the
1466standard output and error streams are plugged into), _INFO_-level lines
770538dd 1467are blue, _WARNING_-level lines are yellow, and _ERROR_-level and
f9ded0e0
PP
1468_FATAL_-level lines are red.
1469
1470Log line example:
beb0fb75 1471
cd4aac1e
PP
1472----
147305-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
1474----
beb0fb75 1475
cd4aac1e
PP
1476You can easily filter the log with `grep` or `ag`. For example, to keep
1477only the _DEBUG_-level logging messages that the `FIELD-CLASS` module
beb0fb75
PP
1478generates:
1479
cd4aac1e
PP
1480----
1481$ babeltrace2 --log-level=D /path/to/trace |& ag 'D FIELD-CLASS'
1482----
1483
1484
1485== Valgrind
1486
1487To use Valgrind on an application (for example, the CLI or a test) which
1488loads libbabeltrace2, use:
1489
1490----
1491$ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \
916d0d91 1492 LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full app
cd4aac1e
PP
1493----
1494
1495`G_SLICE=always-malloc` and `G_DEBUG=gc-friendly` is for GLib and
1496`PYTHONMALLOC=malloc` is for the Python interpreter, if it is used by
1497the Python plugin provider (Valgrind will probably show a lot of errors
1498which originate from the Python interpreter anyway).
1499
16b7b5e7 1500`LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
cd4aac1e
PP
1501libraries (plugins) which it loads. You need this to see the appropriate
1502backtrace when Valgrind shows errors.
c637d729
FD
1503
1504== Testing
1505
800400d8
PP
1506[[test-env]]
1507=== Environment
c637d729 1508
800400d8
PP
1509`tests/utils/utils.sh` sets the environment variables for any Babeltrace
1510test script.
1511
1512`utils.sh` only needs to know the path to the `tests` directory within
1513the source and the build directories. By default, `utils.sh` assumes the
1514build is in tree, that is, you ran `./configure` from the source's root
1515directory, and sets the `BT_TESTS_SRCDIR` and `BT_TESTS_BUILDDIR`
1516environment variables accordingly. You can override those variables, for
1517example if you build out of tree.
1518
1519All test scripts eventually do something like this to source `utils.sh`,
1520according to where they are located relative to the `tests` directory:
1521
1522[source,bash]
1523----
1524if [ "x${BT_TESTS_SRCDIR:-}" != "x" ]; then
1525 UTILSSH="$BT_TESTS_SRCDIR/utils/utils.sh"
1526else
1527 UTILSSH="$(dirname "$0")/../utils/utils.sh"
1528fi
1529----
1530
1531==== Python
1532
1533You can use the `tests/utils/run_python_bt2` script to run any command
1534within an environment making the build's `bt2` Python package available.
1535
1536`run_python_bt2` uses <<test-env,`utils.sh`>> which needs to know the
1537build directory, so make sure you set the `BT_TESTS_BUILDDIR`
1538environment variable correctly _if you build out of tree_, for example:
1539
1540----
1541$ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests
1542----
1543
1544You can run any command which needs the `bt2` Python package through
1545`run_python_bt2`, for example:
c637d729
FD
1546
1547----
800400d8 1548$ ./tests/utils/run_python_bt2 ipython3
c637d729
FD
1549----
1550
800400d8
PP
1551=== Report format
1552
1553All test scripts output the test results following the
1554https://testanything.org/[Test Anything Protocol] (TAP) format.
1555
1556The TAP format has two mechanisms to print additional information about
1557a test:
1558
1559* Print a line starting with `#` to the standard output.
1560+
1561This is usually done with the `diag()` C function or the `diag` shell
1562function.
1563
1564* Print to the standard error.
1565
1566
1567=== Python bindings
1568
1569The `bt2` Python package tests are located in
1570`tests/bindings/python/bt2`.
1571
1572
1573==== Python test runner
1574
1575`tests/utils/python/testrunner.py` is Babeltrace's Python test runner
1576which loads Python files containing unit tests, finds all the test
1577cases, and runs the tests, producing a TAP report.
1578
1579You can see the test runner command's help with:
c637d729
FD
1580
1581----
800400d8 1582$ python3 ./tests/utils/python/testrunner.py --help
c637d729
FD
1583----
1584
800400d8
PP
1585By default, the test runner reports failing tests (TAP's `not{nbsp}ok`
1586line), but continues to run other tests. You can use the `--failfast`
1587option to make the test runner fail as soon as a test fails.
c637d729 1588
800400d8
PP
1589
1590==== Guides
1591
1592To run all the `bt2` Python package tests:
1593
1594* Run:
1595+
1596----
1597$ ./tests/utils/run_python_bt2 ./tests/bindings/python/bt2/test_python_bt2
1598----
1599+
1600or:
1601+
1602----
1603$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
1604 ./tests/bindings/python/bt2/ -p '*.py'
1605----
1606
1607To run **all the tests** in a test module (for example,
1608`test_value.py`):
1609
1610* Run:
1611+
1612----
1613$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
1614 ./tests/bindings/python/bt2 -t test_value
1615----
1616
1617To run a **specific test case** (for example, `RealValueTestCase` within
1618`test_value.py`):
1619
1620* Run:
1621+
1622----
1623$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
1624 ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase
1625----
1626
1627To run a **specific test** (for example,
1628`RealValueTestCase.test_assign_pos_int` within `test_value.py`):
1629
1630* Run:
1631+
c637d729 1632----
800400d8
PP
1633$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
1634 ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int
c637d729 1635----
This page took 0.120874 seconds and 4 git commands to generate.