+[[lib-logging-statements]]
+==== Library-specific logging statement macros
+
+The Babeltrace library contains an internal logging API based on the
+generic logging framework. You can use it to log known Babeltrace
+objects without having to manually log each member.
+
+See <<logging-instrument-c-file-lib,Instrument a library C source file>>
+and <<logging-instrument-h-file-lib,Instrument a library C header file>> to
+learn how to be able to use the following macros.
+
+The library logging statement macros are named `+BT_LIB_LOG*()+` instead
+of `+BT_LOG*()+`:
+
+`+BT_LIB_LOGT("format string", ...)+`::
+ Library trace logging statement.
+
+`+BT_LIB_LOGD("format string", ...)+`::
+ Library debug logging statement.
+
+`+BT_LIB_LOGI("format string", ...)+`::
+ Library info logging statement.
+
+`+BT_LIB_LOGW("format string", ...)+`::
+ Library warning logging statement.
+
+`+BT_LIB_LOGE("format string", ...)+`::
+ Library error logging statement.
+
+`+BT_LIB_LOGF("format string", ...)+`::
+ Library fatal logging statement.
+
+The macros above accept the typical `printf()` conversion specifiers
+with the following limitations:
+
+* The `+*+` width specifier is not accepted.
+* The `+*+` precision specifier is not accepted.
+* The `j` and `t` length modifiers are not accepted.
+* The `n` format specifier is not accepted.
+* The format specifiers defined in `<inttypes.h>` are not accepted,
+ except for `PRId64`, `PRIu64`, `PRIx64`, `PRIX64`, `PRIo64`, and
+ `PRIi64`.
+
+The Babeltrace library custom conversion specifier is accepted. Its
+syntax is either `%!u` to format a UUID (`bt_uuid` type), or:
+
+. Introductory `%!` sequence.
+
+. **Optional**: `[` followed by a custom prefix for the printed fields
+ of this specifier, followed by `]`. The standard form is to end this
+ prefix with `-` so that, for example, with the prefix `tc-`, the
+ complete field name becomes `tc-addr`.
+
+. **Optional**: `pass:[+]` to print extended object members. This
+ depends on the provided format specifier.
+
+. Format specifier (see below).
+
+The available format specifiers are:
+
+[options="header,autowidth",cols="3"]
+|===
+|Specifier
+|Object
+|Expected C type
+
+|`F`
+|Trace IR field class
+|`+struct bt_field_class *+`
+
+|`f`
+|Trace IR field
+|`+struct bt_field *+`
+
+|`P`
+|Trace IR field path
+|`+struct bt_field_path *+`
+
+|`E`
+|Trace IR event class
+|`+struct bt_event_class *+`
+
+|`e`
+|Trace IR event
+|`+struct bt_event *+`
+
+|`S`
+|Trace IR stream class.
+|`+struct bt_stream_class *+`
+
+|`s`
+|Trace IR stream
+|`+struct bt_stream *+`
+
+|`a`
+|Trace IR packet
+|`+struct bt_packet *+`
+
+|`T`
+|Trace IR trace class
+|`+struct bt_trace_class *+`
+
+|`t`
+|Trace IR trace
+|`+struct bt_trace *+`
+
+|`K`
+|Trace IR clock class
+|`+struct bt_clock_class *+`
+
+|`k`
+|Trace IR clock snapshot
+|`+struct bt_clock_snapshot *+`
+
+|`v`
+|Value object
+|`+struct bt_value *+`
+
+|`n`
+|Message
+|`+struct bt_message *+`
+
+|`i`
+|Message iterator
+|`struct bt_message_iterator *`
+
+|`C`
+|Component class
+|`struct bt_component_class *`
+
+|`c`
+|Component
+|`+struct bt_component *+`
+
+|`p`
+|Port
+|`+struct bt_port *+`
+
+|`x`
+|Connection
+|`+struct bt_connection *+`
+
+|`g`
+|Graph
+|`+struct bt_graph *+`
+
+|`l`
+|Plugin
+|`const struct bt_plugin *`
+
+|`o`
+|Object pool
+|`+struct bt_object_pool *+`
+
+|`O`
+|Object
+|`+struct bt_object *+`
+|===
+
+Conversion specifier examples:
+
+* `%!f`
+* `%![my-event-]+e`
+* `%!t`
+* `%!+F`
+
+The ``, `` string (comma and space) is printed between individual
+fields, but **not after the last one**. Therefore, you must put this
+separator in the format string between two conversion specifiers, for
+example:
+
+[source,c]
+----
+BT_LIB_LOGW("Message: count=%u, %!E, %!+K", count, event_class, clock_class);
+----
+
+Example with a custom prefix:
+
+[source,c]
+----
+BT_LIB_LOGI("Some message: %![ec-a-]e, %![ec-b-]+e", ec_a, ec_b);
+----
+
+It is safe to pass `NULL` as any Babeltrace object parameter: the macros
+only print its null address.
+
+WARNING: Build-time `printf()` format checks are disabled for the
+`+BT_LIB_LOG*()+` macros because there are custom conversion specifiers,
+so make sure to test your logging statements.
+
+
+[[comp-logging-statements]]
+==== Component-specific logging statement macros
+
+There are available logging macros for components. They prepend a prefix
+including the component's name to the logging message.
+
+See <<logging-instrument-c-file-compcls,Instrument a component class C
+source file>> and <<logging-instrument-h-file-compcls,Instrument a
+component class C header file>> to learn how to be able to use the
+following macros.
+
+The component logging statement macros are named `+BT_COMP_LOG*()+`
+instead of `+BT_LOG*()+`:
+
+`+BT_COMP_LOGT("format string", ...)+`::
+ Component trace logging statement.
+
+`+BT_COMP_LOGD("format string", ...)+`::
+ Component debug logging statement.
+
+`+BT_COMP_LOGI("format string", ...)+`::
+ Component info logging statement.
+
+`+BT_COMP_LOGW("format string", ...)+`::
+ Component warning logging statement.
+
+`+BT_COMP_LOGE("format string", ...)+`::
+ Component error logging statement.
+
+`+BT_COMP_LOGF("format string", ...)+`::
+ Component fatal logging statement.
+
+`+BT_COMP_LOGT_STR("preformatted string")+`::
+ Component preformatted string trace logging statement.
+
+`+BT_COMP_LOGD_STR("preformatted string")+`::
+ Component preformatted string debug logging statement.
+
+`+BT_COMP_LOGI_STR("preformatted string")+`::
+ Component preformatted string info logging statement.
+
+`+BT_COMP_LOGW_STR("preformatted string")+`::
+ Component preformatted string warning logging statement.
+
+`+BT_COMP_LOGE_STR("preformatted string")+`::
+ Component preformatted string error logging statement.
+
+`+BT_COMP_LOGF_STR("preformatted string")+`::
+ Component preformatted string fatal logging statement.
+
+`+BT_COMP_LOGT_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string trace logging statement.
+
+`+BT_COMP_LOGD_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string debug logging statement.
+
+`+BT_COMP_LOGI_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string info logging statement.
+
+`+BT_COMP_LOGW_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string warning logging statement.
+
+`+BT_COMP_LOGE_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string error logging statement.
+
+`+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string fatal logging statement.
+
+`+BT_COMP_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory trace logging statement.
+
+`+BT_COMP_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory debug logging statement.
+
+`+BT_COMP_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory info logging statement.
+
+`+BT_COMP_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory warning logging statement.
+
+`+BT_COMP_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory error logging statement.
+
+`+BT_COMP_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory fatal logging statement.