tracetools_trace.tools.lttng_impl module

Implementation of the interface for tracing with LTTng.

tracetools_trace.tools.lttng_impl.destroy(*, session_name: str, ignore_error: bool = False, **kwargs) → None

Destroy LTTng session, and check for errors.

This must not be called if lttngpy.is_available() is False. Raises RuntimeError on failure to destroy, unless ignored.

Parameters:

session_name – the name of the session
ignore_error – whether to ignore any error when destroying

tracetools_trace.tools.lttng_impl.get_lttng_home() → str | None

Get the LTTng home value.

$LTTNG_HOME, or $HOME if unset: https://lttng.org/man/1/lttng/v2.13/#doc-_files

Returns:: the LTTng home value

tracetools_trace.tools.lttng_impl.get_session_daemon_pid() → int | None

Get the non-root session daemon PID, if there is one.

This does not apply to root session daemons.

Returns:: the non-root session daemon PID, or None if there is none

tracetools_trace.tools.lttng_impl.get_version() → Version | None

Get version of lttng-ctl.

Returns:: the version as a Version object, or None if it cannot be extracted

tracetools_trace.tools.lttng_impl.is_kernel_tracer_available() → bool

Check if the kernel tracer is available.

This must not be called if lttngpy.is_available() is False.

Returns:: True if available or False if not

tracetools_trace.tools.lttng_impl.is_session_daemon_not_alive() → bool

Check if the session daemon isn’t alive.

This must not be called if lttngpy.is_available() is False.

Returns:: True if the session daemon is not alive, or False if it is alive

tracetools_trace.tools.lttng_impl.is_session_daemon_unreachable() → bool

Check if the session daemon appears to exist while being unreachable.

This tries to detect cases of this LTTng issue: https://bugs.lttng.org/issues/1371 If this issue happens, LTTng will think that the session daemon exists and will happily trace, but it will silently not record any trace data, since there is no actual session daemon. Therefore, if this returns True, then tracing will silently not work.

TODO(christophebedard) remove this once Rolling uses a version of LTTng with a fix for this bug

Returns:: True if the session daemon is unreachable, False otherwise

tracetools_trace.tools.lttng_impl.setup(*, session_name: str, base_path: str, append_trace: bool = False, ros_events: List[str] | Set[str] = ['ros2:rcl_init', 'ros2:rcl_node_init', 'ros2:rmw_publisher_init', 'ros2:rcl_publisher_init', 'ros2:rclcpp_publish', 'ros2:rclcpp_intra_publish', 'ros2:rcl_publish', 'ros2:rmw_publish', 'ros2:rmw_subscription_init', 'ros2:rcl_subscription_init', 'ros2:rclcpp_subscription_init', 'ros2:rclcpp_subscription_callback_added', 'ros2:rmw_take', 'ros2:rcl_take', 'ros2:rclcpp_take', 'ros2:rcl_service_init', 'ros2:rclcpp_service_callback_added', 'ros2:rcl_client_init', 'ros2:rcl_timer_init', 'ros2:rclcpp_timer_callback_added', 'ros2:rclcpp_timer_link_node', 'ros2:rclcpp_callback_register', 'ros2:callback_start', 'ros2:callback_end', 'ros2:rcl_lifecycle_state_machine_init', 'ros2:rcl_lifecycle_transition', 'ros2:rclcpp_executor_get_next_ready', 'ros2:rclcpp_executor_wait_for_work', 'ros2:rclcpp_executor_execute', 'ros2:rclcpp_ipb_to_subscription', 'ros2:rclcpp_buffer_to_ipb', 'ros2:rclcpp_construct_ring_buffer', 'ros2:rclcpp_ring_buffer_enqueue', 'ros2:rclcpp_ring_buffer_dequeue', 'ros2:rclcpp_ring_buffer_clear'], kernel_events: List[str] | Set[str] = [], context_fields: List[str] | Set[str] | Dict[str, List[str]] = ['procname', 'vpid', 'vtid'], channel_name_ust: str = 'ros2', channel_name_kernel: str = 'kchan', subbuffer_size_ust: int = 32768, subbuffer_size_kernel: int = 131072) → str | None

Set up LTTng session, with events and context.

See: https://lttng.org/docs/#doc-core-concepts

Initialization will fail if the list of kernel events to be enabled is not empty and if the kernel tracer is not installed.

This must not be called if lttngpy.is_available() is False. Raises RuntimeError on failure, in which case the tracing session might still exist.

Parameters:

session_name – the name of the session
base_path – the path to the directory in which to create the tracing session directory, which will be created if needed
append_trace – whether to append to the trace directory if it already exists, otherwise an error is reported
ros_events – list of ROS events to enable
kernel_events – list of kernel events to enable
context_fields –
the names of context fields to enable if it’s a list or a set, the context fields are enabled for both kernel and userspace; if it’s a dictionary: { domain type string -> context fields list }

with the domain type string being either names.DOMAIN_TYPE_KERNEL or names.DOMAIN_TYPE_USERSPACE
channel_name_ust – the UST channel name
channel_name_kernel – the kernel channel name
subbuffer_size_ust – the size of the subbuffers for userspace events (defaults to 8 times the usual page size)
subbuffer_size_kernel – the size of the subbuffers for kernel events (defaults to 32 times the usual page size, since there can be way more kernel events than UST events)

Returns:

the full path to the trace directory, or None if initialization failed

tracetools_trace.tools.lttng_impl.spawn_session_daemon() → None

Try to spawn a session daemon.

Raises RuntimeError if lttng-sessiond is not found.

tracetools_trace.tools.lttng_impl.start(*, session_name: str, **kwargs) → None

Start LTTng session, and check for errors.

This must not be called if lttngpy.is_available() is False. Raises RuntimeError on failure to start.

Parameters:: session_name – the name of the session

tracetools_trace.tools.lttng_impl.stop(*, session_name: str, ignore_error: bool = False, **kwargs) → None

Stop LTTng session, and check for errors.

This must not be called if lttngpy.is_available() is False. Raises RuntimeError on failure to stop, unless ignored.

Parameters:

session_name – the name of the session
ignore_error – whether to ignore any error when stopping