+is enabled or not for them, and if so, what is their
+<<choose-a-logging-tag,logging tag>> and <<run-time-log-level,run-time
+log level>> expression.
+
+.. Require that logging be enabled:
++
+[source,c]
+----
+/* Protection: this file uses BT_LOG*() macros directly */
+#ifndef BT_LOG_SUPPORTED
+# error Please include "logging/log.h" before including this file.
+#endif
+----
++
+Then, in the file, instrument your code with the
+<<gen-logging-statements,generic logging statement macros>>.
+
+
+[[logging-instrument-c-file-lib]]
+==== Instrument a library C source file
+
+To instrument a library C source file (`.c`):
+
+. At the top of the file, before the first `#include` line (if any),
+ define your file's <<choose-a-logging-tag,logging tag>> name (this
+ tag must start with `LIB/`):
++
+--
+[source,c]
+----
+#define BT_LOG_TAG "LIB/THE-FILE"
+----
+--
+
+. Include `"lib/logging.h"`:
++
+[source,c]
+----
+#include "lib/logging.h"
+----
+
+. In the file, instrument your code with the
+ <<lib-logging-statements,library logging statement macros>> or with
+ the <<gen-logging-statements,generic logging statement macros>>.
+
+
+[[logging-instrument-h-file-lib]]
+==== Instrument a library C header file
+
+To instrument a library C header file (`.h`), if you have `static
+inline` functions in it:
+
+. Do not include `"lib/logging.h"`!
+
+. Require that library logging be enabled:
++
+[source,c]
+----
+/* Protection: this file uses BT_LIB_LOG*() macros directly */
+#ifndef BT_LIB_LOG_SUPPORTED
+# error Please include "lib/logging.h" before including this file.
+#endif
+----
+
+. In the file, instrument your code with the
+ <<lib-logging-statements,library logging statement macros>> or with
+ the <<gen-logging-statements,generic logging statement macros>>.
+
+
+[[logging-instrument-c-file-compcls]]
+==== Instrument a component class C source file
+
+To instrument a component class C source file (`.c`):
+
+. At the top of the file, before the first `#include` line (if any),
+ define your file's <<choose-a-logging-tag,logging tag>> name (this tag
+ must start with `PLUGIN/` followed by the component class identifier):
++
+--
+[source,c]
+----
+#define BT_LOG_TAG "PLUGIN/SRC.MY-PLUGIN.MY-SRC"
+----
+--
+
+. Below the line above, define the source file's log level expression,
+ `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
+ <<comp-logging-statements,logging statement>> to know the current
+ <<run-time-log-level,run-time log level>>.
++
+For a component class file, it is usually a member of a local component
+private structure variable:
++
+[source,c]
+----
+#define BT_LOG_OUTPUT_LEVEL (my_comp->log_level)
+----
+
+. Below the line above, define `BT_COMP_LOG_SELF_COMP` to an expression
+ which, evaluated in the context of the
+ <<comp-logging-statements,logging statements>>, evaluates to the self
+ component address (`+bt_self_component *+`) of the component.
++
+This is usually a member of a local component private structure
+variable:
++
+[source,c]
+----
+#define BT_COMP_LOG_SELF_COMP (my_comp->self_comp)
+----
+
+. Include `"plugins/comp-logging.h"`:
++
+[source,c]
+----
+#include "plugins/comp-logging.h"
+----
+
+. In the component initialization method, make sure to set the
+ component private structure's log level member to the initial
+ component's log level:
++
+[source,c]
+----
+struct my_comp {
+ bt_logging_level log_level;
+ /* ... */
+};
+
+BT_HIDDEN
+bt_self_component_status my_comp_init(
+ bt_self_component_source *self_comp_src,
+ bt_value *params, void *init_method_data)
+{
+ struct my_comp *my_comp = g_new0(struct my_comp, 1);
+ bt_self_component *self_comp =
+ bt_self_component_source_as_self_component(self_comp_src);
+ const bt_component *comp = bt_self_component_as_component(self_comp);
+
+ BT_ASSERT(my_comp);
+ my_comp->log_level = bt_component_get_logging_level(comp);
+
+ /* ... */
+}
+----
+
+. In the file, instrument your code with the
+ <<comp-logging-statements,component logging statement macros>>.
+
+
+[[logging-instrument-h-file-compcls]]
+==== Instrument a component class C header file
+
+To instrument a component class C header file (`.h`), if you have
+`static inline` functions in it:
+
+. Do not include `"plugins/comp-logging.h"`!
+
+. Require that component logging be enabled:
++
+[source,c]
+----
+/* Protection: this file uses BT_COMP_LOG*() macros directly */
+#ifndef BT_COMP_LOG_SUPPORTED
+# error Please include "plugins/comp-logging.h" before including this file.
+#endif
+----
+
+. In the file, instrument your code with the
+ <<comp-logging-statements,component logging statement macros>>.
+
+
+[[choose-a-logging-tag]]
+==== Choose a logging tag
+
+Each logging-enabled C source file must define `BT_LOG_TAG` to a logging
+tag. A logging tag is a namespace to identify the logging messages of
+this specific source file.