Logging

Detailed Description

Logging level enumerators and library logging control.

The logging API offers logging level enumerators (bt_logging_level) as well as functions to control libbabeltrace2's internal logging.

Note

This API does not offer macros and functions to write logging statements: as of Babeltrace 2.0, the actual mechanism to log is implementation-defined for each user plugin.

libbabeltrace2 contains many hundreds of logging statements to help you follow and debug your plugin or program.

The LIBBABELTRACE2_INIT_LOG_LEVEL environment variable controls the initial logging level of the library. If this environment variable isn't set at library load time, then the initial logging level of the library is BT_LOGGING_LEVEL_NONE. See Logging to learn more.

Set libbabeltrace2's current logging level with bt_logging_set_global_level().

bt_logging_set_global_level() only controls libbabeltrace2's logging level; it does not control the logging level of:

• Individual components: bt_graph_add_source_component(), bt_graph_add_source_component_with_initialize_method_data(), bt_graph_add_filter_component(), bt_graph_add_filter_component_with_initialize_method_data(), bt_graph_add_sink_component(), and bt_graph_add_sink_component_with_initialize_method_data() control this.
• A query operation: bt_query_executor_set_logging_level() controls this.
• The bt_get_greatest_operative_mip_version() or bt_get_greatest_operative_mip_version_with_restriction() operation: its logging_level parameter controls this.

As of Babeltrace 2.0, there's no module-specific logging level control: bt_logging_set_global_level() sets the logging level of all the modules of the library.

libbabeltrace2 writes its logging statements to the standard error stream. A logging line looks like this:

05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0

See Logging to learn more about the format of a logging statement line.

You can set a minimal logging level at the Babeltrace 2 project build time (see Logging to learn how). The logging statements with a level that's less severe than the minimal logging level are not built. For example, if the minimal logging level is BT_LOGGING_LEVEL_INFO, then the BT_LOGGING_LEVEL_TRACE and BT_LOGGING_LEVEL_DEBUG logging statements aren't built. Use bt_logging_get_minimal_level() to get the minimal logging level of the library.

Typedefs
typedef enum bt_logging_level	bt_logging_level
	Logging level enumerators.

Enumerations
enum	bt_logging_level {   BT_LOGGING_LEVEL_TRACE ,   BT_LOGGING_LEVEL_DEBUG ,   BT_LOGGING_LEVEL_INFO ,   BT_LOGGING_LEVEL_WARNING ,   BT_LOGGING_LEVEL_ERROR ,   BT_LOGGING_LEVEL_FATAL ,   BT_LOGGING_LEVEL_NONE }
	Logging level enumerators. More...

Functions
void	bt_logging_set_global_level (bt_logging_level logging_level)
	Sets the logging level of all the libbabeltrace2 modules to logging_level.
bt_logging_level	bt_logging_get_global_level (void)
	Returns the current logging level of all the libbabeltrace2 modules.
bt_logging_level	bt_logging_get_minimal_level (void)
	Returns the minimal (build-time) logging level of the library.

Enumeration Type Documentation

bt_logging_level

enum bt_logging_level

Logging level enumerators.

Enumerator
BT_LOGGING_LEVEL_TRACE	TRACE level. Low-level debugging context information. The TRACE logging statements can significantly impact performance.
BT_LOGGING_LEVEL_DEBUG	DEBUG level. Debugging information, with a higher level of details than the TRACE level. The DEBUG logging statements don't significantly impact performance.
BT_LOGGING_LEVEL_INFO	INFO level. Informational messages that highlight progress or important states of the application, plugins, or library. The INFO logging statements don't significantly impact performance.
BT_LOGGING_LEVEL_WARNING	WARNING level. Unexpected situations which still allow the execution to continue. The WARNING logging statements don't significantly impact performance.
BT_LOGGING_LEVEL_ERROR	ERROR level. Errors that might still allow the execution to continue. Usually, once one or more errors are reported at this level, the application, plugin, or library won't perform any more useful task, but it should still exit cleanly. The ERROR logging statements don't significantly impact performance.
BT_LOGGING_LEVEL_FATAL	FATAL level. Severe errors that lead the execution to abort immediately. The FATAL logging statements don't significantly impact performance.
BT_LOGGING_LEVEL_NONE	Logging is disabled.

Function Documentation

bt_logging_set_global_level()

void bt_logging_set_global_level ( bt_logging_level logging_level )

extern

Sets the logging level of all the libbabeltrace2 modules to logging_level.

The global logging level of the library doesn't affect the logging level of individual components and query operations.

Parameters

[in]

logging_level

New global logging level of the library.

See also

bt_logging_get_global_level() — Returns the current global logging level of the library.

bt_logging_get_global_level()

bt_logging_level bt_logging_get_global_level ( void )

extern

Returns the current logging level of all the libbabeltrace2 modules.

Returns

Current global logging level of the library.

See also

bt_logging_set_global_level() — Sets the global logging level of the current library.

bt_logging_get_minimal_level()

bt_logging_level bt_logging_get_minimal_level ( void )

extern

Returns the minimal (build-time) logging level of the library.

The library logging statements with a level that's less severe than the minimal logging level are not built.

For example, if the minimal logging level is BT_LOGGING_LEVEL_INFO, then the BT_LOGGING_LEVEL_TRACE and BT_LOGGING_LEVEL_DEBUG logging statements aren't built.

Returns

Minimal logging level of the library.

See also

bt_logging_get_global_level() — Returns the current global logging level of the library.