+
The default build-time log level is `DEBUG`. For optimal performance,
set it to `INFO`, which effectively disables all fast path logging in
-all the Babeltrace modules.
+all the Babeltrace modules. You can't set it to `WARN`, `ERROR`,
+`FATAL`, or `NONE` because the impact on performance is minuscule
+starting from the _INFO_ log level anyway and we want any Babeltrace
+build to always be able to print _INFO_-level logs.
+
The library's public API provides `bt_logging_get_minimal_level()` to
get the configured minimal log level.
`+BT_LIB_LOGF("format string", ...)+`::
Library fatal logging statement.
+`+BT_LIB_LOGW_APPEND_CAUSE("format string", ...)+`::
+ Library warning logging statement, and unconditional error cause
+ appending.
+
+`+BT_LIB_LOGE_APPEND_CAUSE("format string", ...)+`::
+ Library error logging statement, and unconditional error cause
+ appending.
+
+`+BT_LIB_LOGF_APPEND_CAUSE("format string", ...)+`::
+ Library fatal logging statement, and unconditional error cause
+ appending.
+
The macros above accept the typical `printf()` conversion specifiers
with the following limitations:
|Plugin
|`const struct bt_plugin *`
+|`r`
+|Error cause
+|`const struct bt_error_cause *`
+
|`o`
|Object pool
|`+struct bt_object_pool *+`
* Failed assertion (within `BT_ASSERT()`).
* Unsatisfied library precondition (within `BT_ASSERT_PRE()`).
* Unsatisfied library postcondition (within `BT_ASSERT_POST()`).
-|Almost none: should be executed in production.
+|Almost none: always enabled.
|_ERROR_
|
failure to create an empty object (no parameters): most probably
failed internally because of an allocation error.
* Almost any error in terminal elements: CLI and plugins.
-|Almost none: should be executed in production.
+|Almost none: always enabled.
|_WARN_
|
* Missing data within something that is expected to have it, but there's
an alternative.
* Invalid file, but recoverable/fixable.
-|Almost none: can be executed in production.
+|Almost none: always enabled.
|_INFO_
|
* An _optional_ subsystem cannot be loaded.
* An _optional_ field/datum cannot be found.
|
-Very little: can be executed in production if _INFO_ level information
-is desired.
+Very little: always enabled.
|_DEBUG_
|
`LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
libraries (plugins) which it loads. You need this to see the appropriate
backtrace when Valgrind shows errors.
+
+== Testing
+
+=== Python Bindings
+
+To run all the `bt2` Python package tests use:
+
+----
+$ BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests \
+ ./tests/bindings/python/bt2/test_python_bt2
+----
+
+To run all the tests in a test module (e.g. `test_event.py`) use:
+
+----
+$ BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests \
+ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ -t test_event \
+ ./tests/bindings/python/bt2/
+----
+
+To run a specific test (e.g. `EventTestCase.test_clock_value`) in a test module
+(e.g. `test_event.py`) use:
+
+----
+$ BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests \
+ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ -t test_event.EventTestCase.test_clock_value \
+ ./tests/bindings/python/bt2/
+----