Skip to content

Commit b21057c

Browse files
christophebedardiluetkeb
christophebedard
authored and
iluetkeb
committed
Update tracing tutorial (#80)
* Remove 'upcoming work' list * Update tracing commands and tutorial * Update process command output figure * Update tracing tutorial plots * Re-word clone section and add details * Remove dashing tracing setup section
1 parent dc70d24 commit b21057c

4 files changed

Lines changed: 18 additions & 34 deletions

File tree

‎_docs/tutorials/advanced/tracing/index.md‎

Lines changed: 11 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -48,29 +48,22 @@ If the ROS 2 development tools and dependencies are not installed on your machin
4848
Now we'll download all the necessary packages. First, create your workspace.
4949

5050
```bash
51-
$ mkdir ~/ros2_ws
51+
$ mkdir -p ~/ros2_ws/src
5252
$ cd ros2_ws/
5353
```
5454

55-
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.
55+
The `rcl` and `rclcpp` instrumentation has been integrated into Eloquent, so we simply need to recompile `ros2_tracing` & compile `tracetools_analysis`.
5656

57-
#### Clone source on ROS 2 eloquent
5857
```bash
5958
$ wget https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing/raw/master/tracing.repos
6059
$ vcs import src < tracing.repos
6160
```
62-
#### Clone source on ROS 2 dashing
63-
You can also use tracing on dashing already, but will have to build from scratch
64-
```bash
65-
$ wget https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing/raw/master/all.repos
66-
$ vcs import src < all.repos
67-
```
6861

69-
#### Let's build everything and source!
62+
Now let's build and source.
7063

7164
```bash
72-
$ colcon build --symlink-install --cmake-args " -DWITH_LTTNG=ON"
73-
$ source ./install/local_setup.bash
65+
$ colcon build --symlink-install
66+
$ source install/local_setup.bash
7467
```
7568

7669
## Simple tracing example
@@ -91,7 +84,7 @@ $ ros2 launch tracetools_launch example.launch.py
9184

9285
As shown above, you should see a few output lines, and that's it.
9386

94-
You can take a look at the trace's events using `babeltrace`.
87+
By default, traces are written in the `~/.ros/tracing/` directory. You can take a look at the trace's events using `babeltrace`.
9588

9689
```bash
9790
$ cd ~/.ros/tracing/
@@ -108,13 +101,12 @@ $ babeltrace my-tracing-session/ust/
108101
<img src="/img/tutorials/tracing_babeltrace.svg" style="padding: 10px;" />
109102
</center>
110103

111-
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.
104+
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.
112105

113-
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.
106+
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.
114107

115108
```bash
116-
$ ros2 run tracetools_analysis convert ~/.ros/tracing/my-tracing-session/ust
117-
$ ros2 run tracetools_analysis process ~/.ros/tracing/my-tracing-session/ust/pickle
109+
$ ros2 trace-analysis process ~/.ros/tracing/my-tracing-session/ust/
118110
```
119111

120112
<center>
@@ -143,16 +135,6 @@ The resulting plots for the `/ping` and `/pong` subscriptions are shown below. W
143135
<img src="/img/tutorials/tracing_analysis_plots.png" />
144136
</center>
145137

146-
## Upcoming work
147-
148-
Now that the groundwork is done, the next steps are:
149-
150-
* Submit PRs for `rcl` and `rclcpp` instrumentation. We are aiming for the instrumentation to be included in ROS 2 Eloquent (November 2019).
151-
* Add more analyses.
152-
* Test on real hardware, and compare analysis results to other tools.
153-
* Release first version of packages.
154-
* Work on providing swappable `tracetools` packages (a default package with tracing being disabled, and another one with tracing being enabled).
155-
156-
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).
138+
## Relevant links
157139

158-
Let us know if you have any questions, or if you'd like to get involved!
140+
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).

‎img/tutorials/tracing_analysis_plots.png‎

11.6 KB
Loading

‎img/tutorials/tracing_process.svg‎

Lines changed: 7 additions & 5 deletions
Loading

‎img/tutorials/tracing_result_plot.png‎

10.5 KB
Loading

0 commit comments

Comments
 (0)