diff --git a/_docs/tutorials/advanced/tracing/index.md b/_docs/tutorials/advanced/tracing/index.md index 13450c2a..02a7917f 100644 --- a/_docs/tutorials/advanced/tracing/index.md +++ b/_docs/tutorials/advanced/tracing/index.md @@ -48,29 +48,22 @@ If the ROS 2 development tools and dependencies are not installed on your machin Now we'll download all the necessary packages. First, create your workspace. ```bash -$ mkdir ~/ros2_ws +$ mkdir -p ~/ros2_ws/src $ cd ros2_ws/ ``` -Then clone everything using the following `.repos` file. It includes the core ROS 2 packages with instrumented versions of `rcl` and `rclcpp`, as well as the tracing tools and tracing analysis repos. +The `rcl` and `rclcpp` instrumentation has been integrated into Eloquent, so we simply need to recompile `ros2_tracing` & compile `tracetools_analysis`. -#### Clone source on ROS 2 eloquent ```bash $ wget https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing/raw/master/tracing.repos $ vcs import src < tracing.repos ``` -#### Clone source on ROS 2 dashing -You can also use tracing on dashing already, but will have to build from scratch -```bash -$ wget https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing/raw/master/all.repos -$ vcs import src < all.repos -``` -#### Let's build everything and source! +Now let's build and source. ```bash -$ colcon build --symlink-install --cmake-args " -DWITH_LTTNG=ON" -$ source ./install/local_setup.bash +$ colcon build --symlink-install +$ source install/local_setup.bash ``` ## Simple tracing example @@ -91,7 +84,7 @@ $ ros2 launch tracetools_launch example.launch.py As shown above, you should see a few output lines, and that's it. -You can take a look at the trace's events using `babeltrace`. +By default, traces are written in the `~/.ros/tracing/` directory. You can take a look at the trace's events using `babeltrace`. ```bash $ cd ~/.ros/tracing/ @@ -108,13 +101,12 @@ $ babeltrace my-tracing-session/ust/ -The last part of the `babeltrace` output is shown above. This is a human-readable version of the raw Common Trace Format (CTF) data, which is a list of events. Each event has a timestamp, an event type, some information on the process that generated the event, and the fields corresponding to the event type. The last events of our trace are pairs of `ros2:callback_start` and `ros2:callback_end` events. Each contains a reference to its corresponding callback. +The last part of the `babeltrace` output is shown above. This is a human-readable version of the raw Common Trace Format (CTF) data, which is a list of events. Each event has a timestamp, an event type, some information on the process that generated the event, and the fields corresponding to the event type. The last events of our trace are pairs of `ros2:callback_start` and `ros2:callback_end` events. Each one contains a reference to its corresponding callback. -It's now time to process the trace data! The `tracetools_analysis` package provides tools to import and process the results. We can first convert the CTF data to a pickle file. Then we can process it to get `pandas` dataframes which we can use later to run analyses. +It's now time to process the trace data! The `tracetools_analysis` package provides tools to import a trace and process it. Since reading a CTF trace is slow, it first converts it to a file which we can read much faster later on. Then we can process it to get `pandas` dataframes and use those to run analyses. ```bash -$ ros2 run tracetools_analysis convert ~/.ros/tracing/my-tracing-session/ust -$ ros2 run tracetools_analysis process ~/.ros/tracing/my-tracing-session/ust/pickle +$ ros2 trace-analysis process ~/.ros/tracing/my-tracing-session/ust/ ```
@@ -143,16 +135,6 @@ The resulting plots for the `/ping` and `/pong` subscriptions are shown below. W
-## Upcoming work - -Now that the groundwork is done, the next steps are: - -* Submit PRs for `rcl` and `rclcpp` instrumentation. We are aiming for the instrumentation to be included in ROS 2 Eloquent (November 2019). -* Add more analyses. -* Test on real hardware, and compare analysis results to other tools. -* Release first version of packages. -* Work on providing swappable `tracetools` packages (a default package with tracing being disabled, and another one with tracing being enabled). - -The tracing packages can be found [here](https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing). The analysis tools can be found [here](https://gitlab.com/micro-ROS/ros_tracing/tracetools_analysis). +## Relevant links -Let us know if you have any questions, or if you'd like to get involved! +The tracing packages can be found in the [`ros2_tracing` repo](https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing). The analysis tools can be found in the [`tracetools_analysis` repo](https://gitlab.com/micro-ROS/ros_tracing/tracetools_analysis). diff --git a/img/tutorials/tracing_analysis_plots.png b/img/tutorials/tracing_analysis_plots.png index 90259ef1..99331f3d 100644 Binary files a/img/tutorials/tracing_analysis_plots.png and b/img/tutorials/tracing_analysis_plots.png differ diff --git a/img/tutorials/tracing_process.svg b/img/tutorials/tracing_process.svg index c1f044ce..78874c61 100644 --- a/img/tutorials/tracing_process.svg +++ b/img/tutorials/tracing_process.svg @@ -1,7 +1,8 @@ - + - + + + } + ]]> - - 94288517870464 1562746992863837193 9428851751889694288518240160 1562746992864386991 9428851825246494288518609936 1562746992865161707 9428851832027294288519326016 1562746992866382215 9428851456968094288519407744 1562746992866948657 94288519346592Callback symbols: timestamp symbolcallback_object 94258814809568 1562746992861415771 std::_Bind<void (rclcpp::TimeSource::*(rclcpp:...94258819586592 1562746992861940378 std::_Bind<void (PingNode::*(PingNode*, std::_...94258820235240 1562746992862399994 timer94288514569680 1562746992866400686 std::_Bind<void (rclcpp::TimeSource::*(rclcpp:...94288519346592 1562746992866961196 std::_Bind<void (PongNode::*(PongNode*, std::_...Callback instances: callback_object timestamp duration intra_process0 94258820235240 1562746993362567313 115006 False1 94288519346592 1562746993363166546 1180219 False2 94258819586592 1562746993363902477 1227555 False==================================================~/ros2_ws $ + + 94834912015328 1571591844142313253 9483491184475294834912602624 1571591844144610962 9483491260326494342555941376 1571591844146303565 9434255594201694834912611936 1571591844147216388 9483491261220894342555950720 1571591844147522667 9434255595099294834913214080 1571591844147781683 94834913214232Callback symbols: timestamp symbolcallback_object 94834912603264 1571591844144764856 std::_Bind<void (rclcpp::TimeSource::*(rclcpp:...94342555942016 1571591844146338856 std::_Bind<void (rclcpp::TimeSource::*(rclcpp:...94834912612208 1571591844147229360 std::_Bind<void (PingNode::*(PingNode*, std::_...94342555950992 1571591844147535327 std::_Bind<void (PongNode::*(PongNode*, std::_...94834913214232 1571591844147787038 std::_Bind<void (PingNode::*(PingNode*))()>Callback instances: callback_object timestamp duration intra_process0 94834913214232 1571591844647985905 81280 False1 94834912612208 1571591844648979425 735737 False2 94342555950992 1571591844648441867 1312481 False==================================================processed 56 events in 274 ms~/ros2_ws $ \ No newline at end of file diff --git a/img/tutorials/tracing_result_plot.png b/img/tutorials/tracing_result_plot.png index b2608fa0..887089c2 100644 Binary files a/img/tutorials/tracing_result_plot.png and b/img/tutorials/tracing_result_plot.png differ