X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=CONTRIBUTING.adoc;h=c5fb796862a5b799181c3402cff889cfb2bc52d3;hb=6245c710142117a17eea621a5abe8c6f54ca30c1;hp=c800b70e21837bee74b3af45a5531f95e742610b;hpb=7715df7ba83e6b3be83ae96e71ed196e5ce8802f;p=babeltrace.git diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index c800b70e..c5fb7968 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -246,7 +246,7 @@ can find the cause of a bug faster. While <> when placing _DEBUG_ to _FATAL_ logging statements, you should liberally instrument your -Babeltrace module with _VERBOSE_ logging statements to help future you +Babeltrace module with _TRACE_ logging statements to help future you and other developers understand what's happening at run time. @@ -315,10 +315,10 @@ order of severity: |Internal API enumerator |Public API enumerator -|_VERBOSE_ -|`V` -|`BT_LOG_VERBOSE` -|`BT_LOGGING_LEVEL_VERBOSE` +|_TRACE_ +|`T` +|`BT_LOG_TRACE` +|`BT_LOGGING_LEVEL_TRACE` |_DEBUG_ |`D` @@ -330,10 +330,10 @@ order of severity: |`BT_LOG_INFO` |`BT_LOGGING_LEVEL_INFO` -|_WARN_ +|_WARNING_ |`W` -|`BT_LOG_WARN` -|`BT_LOGGING_LEVEL_WARN` +|`BT_LOG_WARNING` +|`BT_LOGGING_LEVEL_WARNING` |_ERROR_ |`E` @@ -374,13 +374,16 @@ You can set this level at configuration time with the + -- ---- -$ BABELTRACE_MINIMAL_LOG_LEVEL=WARN ./configure +$ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./configure ---- -- + 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 `WARNING`, `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. @@ -475,8 +478,8 @@ See <> and <> to learn how to be able to use the following macros. -`+BT_LOGV("format string", ...)+`:: - Generic verbose logging statement. +`+BT_LOGT("format string", ...)+`:: + Generic trace logging statement. `+BT_LOGD("format string", ...)+`:: Generic debug logging statement. @@ -493,8 +496,8 @@ file (generic)>> to learn how to be able to use the following macros. `+BT_LOGF("format string", ...)+`:: Generic fatal logging statement. -`+BT_LOGV_STR("preformatted string")+`:: - Generic preformatted string verbose logging statement. +`+BT_LOGT_STR("preformatted string")+`:: + Generic preformatted string trace logging statement. `+BT_LOGD_STR("preformatted string")+`:: Generic preformatted string debug logging statement. @@ -511,8 +514,8 @@ file (generic)>> to learn how to be able to use the following macros. `+BT_LOGF_STR("preformatted string")+`:: Generic preformatted string fatal logging statement. -`+BT_LOGV_MEM(data_ptr, data_size, "format string", ...)+`:: - Generic memory verbose logging statement. +`+BT_LOGT_MEM(data_ptr, data_size, "format string", ...)+`:: + Generic memory trace logging statement. `+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`:: Generic memory debug logging statement. @@ -529,8 +532,8 @@ file (generic)>> to learn how to be able to use the following macros. `+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`:: Generic memory fatal logging statement. -`+BT_LOGV_ERRNO("initial message", "format string", ...)+`:: - Generic `errno` string verbose logging statement. +`+BT_LOGT_ERRNO("initial message", "format string", ...)+`:: + Generic `errno` string trace logging statement. `+BT_LOGD_ERRNO("initial message", "format string", ...)+`:: Generic `errno` string debug logging statement. @@ -562,8 +565,8 @@ 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_LOGV("format string", ...)+`:: - Library verbose logging statement. +`+BT_LIB_LOGT("format string", ...)+`:: + Library trace logging statement. `+BT_LIB_LOGD("format string", ...)+`:: Library debug logging statement. @@ -580,6 +583,18 @@ of `+BT_LOG*()+`: `+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: @@ -698,6 +713,10 @@ The available format specifiers are: |Plugin |`const struct bt_plugin *` +|`r` +|Error cause +|`const struct bt_error_cause *` + |`o` |Object pool |`+struct bt_object_pool *+` @@ -753,8 +772,8 @@ following macros. The component logging statement macros are named `+BT_COMP_LOG*()+` instead of `+BT_LOG*()+`: -`+BT_COMP_LOGV("format string", ...)+`:: - Component verbose logging statement. +`+BT_COMP_LOGT("format string", ...)+`:: + Component trace logging statement. `+BT_COMP_LOGD("format string", ...)+`:: Component debug logging statement. @@ -771,8 +790,8 @@ instead of `+BT_LOG*()+`: `+BT_COMP_LOGF("format string", ...)+`:: Component fatal logging statement. -`+BT_COMP_LOGV_STR("preformatted string")+`:: - Component preformatted string verbose 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. @@ -789,8 +808,8 @@ instead of `+BT_LOG*()+`: `+BT_COMP_LOGF_STR("preformatted string")+`:: Component preformatted string fatal logging statement. -`+BT_COMP_LOGV_ERRNO("initial message", "format string", ...)+`:: - Component `errno` string verbose 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. @@ -807,8 +826,8 @@ instead of `+BT_LOG*()+`: `+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`:: Component `errno` string fatal logging statement. -`+BT_COMP_LOGV_MEM(data_ptr, data_size, "format string", ...)+`:: - Component memory verbose 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. @@ -857,10 +876,10 @@ block. The available definitions for build-time conditions are: -* `BT_LOG_ENABLED_VERBOSE` +* `BT_LOG_ENABLED_TRACE` * `BT_LOG_ENABLED_DEBUG` * `BT_LOG_ENABLED_INFO` -* `BT_LOG_ENABLED_WARN` +* `BT_LOG_ENABLED_WARNING` * `BT_LOG_ENABLED_ERROR` * `BT_LOG_ENABLED_FATAL` @@ -879,10 +898,10 @@ noticeable impact on performance. The available definitions for run-time conditions are: -* `BT_LOG_ON_VERBOSE` +* `BT_LOG_ON_TRACE` * `BT_LOG_ON_DEBUG` * `BT_LOG_ON_INFO` -* `BT_LOG_ON_WARN` +* `BT_LOG_ON_WARNING` * `BT_LOG_ON_ERROR` * `BT_LOG_ON_FATAL` @@ -991,8 +1010,8 @@ int some_function(int x) { /* ... */ -#ifdef BT_LOGV - BT_LOGV(...); +#ifdef BT_LOGT + BT_LOGT(...); #endif /* ... */ @@ -1249,8 +1268,11 @@ A _FATAL_-level logging statement should always be followed by * Logic error in internal code, for example an unexpected value in a `switch` statement. * Failed assertion (within `BT_ASSERT()`). -* Unsatisfied library precondition (within `BT_ASSERT_PRE()`). -|Almost none: should be executed in production. +* Unsatisfied library precondition (within `BT_ASSERT_PRE()` or + `BT_ASSERT_PRE_DEV()`). +* Unsatisfied library postcondition (within `BT_ASSERT_POST()` or + `BT_ASSERT_POST_DEV()`). +|Almost none: always enabled. |_ERROR_ | @@ -1269,23 +1291,24 @@ least exit cleanly. 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_ +|_WARNING_ | An error which still allows the execution to continue, but you judge that it should be reported to the user. -_WARN_-level logging statements are for any error or weird action that -is directly or indirectly caused by the user, often through some bad -input data. For example, not having enough memory is considered beyond -the user's control, so we always log memory errors with an _ERROR_ level -(not _FATAL_ because we usually don't abort in this condition). +_WARNING_-level logging statements are for any error or weird action +that is directly or indirectly caused by the user, often through some +bad input data. For example, not having enough memory is considered +beyond the user's control, so we always log memory errors with an +_ERROR_ level (not _FATAL_ because we usually don't abort in this +condition). | * 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_ | @@ -1305,8 +1328,7 @@ level is used for sporadic and one-shot events. * 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_ | @@ -1327,11 +1349,11 @@ an _INFO_ build. * Calling user methods and logging the result. * Setting object properties (except fields and values). | -Noticeable, but not as much as the _VERBOSE_ level: could be executed +Noticeable, but not as much as the _TRACE_ level: could be executed in production if you're going to need a thorough log for support tickets without having to rebuild the project. -|_VERBOSE_ +|_TRACE_ | Low-level debugging context information (anything that does not fit the other log levels). More appropriate for tracing in general. @@ -1345,7 +1367,7 @@ other log levels). More appropriate for tracing in general. [IMPORTANT] -- -Make sure not to use a _WARN_ (or higher) log level when the +Make sure not to use a _WARNING_ (or higher) log level when the condition leading to the logging statement can occur under normal circumstances. @@ -1353,7 +1375,7 @@ For example, a public function to get some object or property from an object by name or key that fails to find the value is not a warning scenario: the user could legitimately use this function to check if the name/key exists in the object. In this case, use the -_VERBOSE_ level (or do not log at all). +_TRACE_ level (or do not log at all). -- @@ -1434,7 +1456,7 @@ name and line number, and the <>. When Babeltrace supports terminal color codes (depends on the `BABELTRACE_TERM_COLOR` environment variable's value and what the standard output and error streams are plugged into), _INFO_-level lines -are blue, _WARN_-level lines are yellow, and _ERROR_-level and +are blue, _WARNING_-level lines are yellow, and _ERROR_-level and _FATAL_-level lines are red. Log line example: @@ -1459,7 +1481,7 @@ loads libbabeltrace2, use: ---- $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \ - BABELTRACE_NO_DLCLOSE=1 valgrind --leak-check=full \ + LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full \ --suppressions=/path/to/babeltrace/extras/valgrind/popt.supp app ---- @@ -1468,6 +1490,36 @@ $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \ the Python plugin provider (Valgrind will probably show a lot of errors which originate from the Python interpreter anyway). -`BABELTRACE_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared +`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/ +----