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.

Raises RuntimeError on failure to stop, 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_version() → Version | None

Get the version of the lttng module.

The module does not have a __version__ attribute, but the version is mentioned in its __doc__, and seems to be written in a consistent way across versions.

Returns:

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

tracetools_trace.tools.lttng_impl.is_kernel_tracer_available() → Tuple[bool, str | None]
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.

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 ‘kernel’ or ‘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.start(*, session_name: str, **kwargs) → None

Start LTTng session, and check for errors.

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.

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