{"id":20099150,"url":"https://github.com/ros2/ros2_tracing","last_synced_at":"2025-08-21T09:32:39.143Z","repository":{"id":41805349,"uuid":"236338843","full_name":"ros2/ros2_tracing","owner":"ros2","description":"Tracing tools for ROS 2.","archived":false,"fork":false,"pushed_at":"2025-07-29T20:48:11.000Z","size":3628,"stargazers_count":187,"open_issues_count":16,"forks_count":55,"subscribers_count":21,"default_branch":"rolling","last_synced_at":"2025-07-29T23:06:51.461Z","etag":null,"topics":["instrumentation","performance-analysis","ros","ros2","ros2-tracing","tools","tracing"],"latest_commit_sha":null,"homepage":"https://docs.ros.org/en/rolling/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ros2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-01-26T16:20:15.000Z","updated_at":"2025-07-29T20:48:14.000Z","dependencies_parsed_at":"2023-02-17T09:46:14.686Z","dependency_job_id":"884a5ee0-2f3a-480a-ba24-57106ac50702","html_url":"https://github.com/ros2/ros2_tracing","commit_stats":null,"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/ros2/ros2_tracing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros2%2Fros2_tracing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros2%2Fros2_tracing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros2%2Fros2_tracing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros2%2Fros2_tracing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ros2","download_url":"https://codeload.github.com/ros2/ros2_tracing/tar.gz/refs/heads/rolling","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros2%2Fros2_tracing/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271455631,"owners_count":24762764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["instrumentation","performance-analysis","ros","ros2","ros2-tracing","tools","tracing"],"created_at":"2024-11-13T17:08:30.779Z","updated_at":"2025-08-21T09:32:39.137Z","avatar_url":"https://github.com/ros2.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ros2_tracing\n\n[![GitHub CI](https://github.com/ros2/ros2_tracing/actions/workflows/test.yml/badge.svg?branch=rolling)](https://github.com/ros2/ros2_tracing/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/ros2/ros2_tracing/branch/rolling/graph/badge.svg)](https://codecov.io/gh/ros2/ros2_tracing)\n\nTracing tools for ROS 2.\n\n## Overview\n\n`ros2_tracing` provides [tracing instrumentation](#tracetools) for the core ROS 2 packages.\nIt also provides [tools to configure tracing](#tracing) through [a launch action](#launch-file-trace-action) and a [`ros2` CLI command](#trace-command).\nFor more information about tracing, see the [*What is tracing?*](#what-is-tracing) section.\n\n`ros2_tracing` currently only supports the [LTTng](https://lttng.org/) tracer.\nConsequently, it currently only supports Linux.\n\n\u003e [!NOTE]\n\u003e Make sure to use the right branch, depending on the ROS 2 distro: [use `rolling` for Rolling, `galactic` for Galactic, etc.](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Developer-Guide.html#branches)\n\n## Publications \u0026 presentations\n\n[Read the `ros2_tracing` paper!](https://arxiv.org/abs/2201.00393)\nIf you use or refer to `ros2_tracing`, please cite:\n* C. Bédard, I. Lütkebohle, and M. Dagenais, [\"ros2_tracing: Multipurpose Low-Overhead Framework for Real-Time Tracing of ROS 2,\"](https://arxiv.org/abs/2201.00393) *IEEE Robotics and Automation Letters*, vol. 7, no. 3, pp. 6511–6518, 2022.\n    \u003cdetails\u003e\n    \u003csummary\u003eBibTeX\u003c/summary\u003e\n\n    ```bibtex\n    @article{bedard2022ros2tracing,\n      title={ros2\\_tracing: Multipurpose Low-Overhead Framework for Real-Time Tracing of ROS 2},\n      author={B{\\'e}dard, Christophe and L{\\\"u}tkebohle, Ingo and Dagenais, Michel},\n      journal={IEEE Robotics and Automation Letters},\n      year={2022},\n      volume={7},\n      number={3},\n      pages={6511--6518},\n      doi={10.1109/LRA.2022.3174346}\n    }\n    ```\n    \u003c/details\u003e\n\nThis other paper leverages `ros2_tracing` to analyze and visualize the flow of messages across distributed ROS 2 systems:\n* C. Bédard, P.-Y. Lajoie, G. Beltrame, and M. Dagenais, [\"Message Flow Analysis with Complex Causal Links for Distributed ROS 2 Systems,\"](https://arxiv.org/abs/2204.10208) *Robotics and Autonomous Systems*, vol. 161, p. 104361, 2023.\n    \u003cdetails\u003e\n    \u003csummary\u003eBibTeX\u003c/summary\u003e\n\n    ```bibtex\n    @article{bedard2023messageflow,\n      title={Message flow analysis with complex causal links for distributed {ROS} 2 systems},\n      author={B{\\'e}dard, Christophe and Lajoie, Pierre-Yves and Beltrame, Giovanni and Dagenais, Michel},\n      journal={Robotics and Autonomous Systems},\n      year={2023},\n      volume={161},\n      pages={104361},\n      doi={10.1016/j.robot.2022.104361}\n    }\n    ```\n    \u003c/details\u003e\n\nFinally, check out the following presentations:\n\n* ROSCon 2023: \"Improving Your Application's Algorithms and Optimizing Performance Using Trace Data\" ([video](https://vimeo.com/879001159), [slides](https://roscon.ros.org/2023/talks/Improving_Your_Applications_Algorithms_and_Optimizing_Performance_Using_Trace_Data.pdf))\n* ROS World 2021: \"Tracing ROS 2 with ros2_tracing\" ([video](https://vimeo.com/652633418), [slides](https://github.com/ros2/ros2_tracing/blob/rolling/doc/2021-10-20_ROS_World_2021_-_Tracing_ROS_2_with_ros2_tracing.pdf))\n\n## Tutorials \u0026 demos\n\n* ROS 2 documentation:\n    * [Building ROS 2 with tracing](https://docs.ros.org/en/rolling/How-To-Guides/Building-ROS-2-with-Tracing.html)\n    * [How to use `ros2_tracing` to trace and analyze an application](https://docs.ros.org/en/rolling/Tutorials/Advanced/ROS2-Tracing-Trace-and-Analyze.html)\n* ROS World 2021 demo: [github.com/christophebedard/ros-world-2021-demo](https://github.com/christophebedard/ros-world-2021-demo)\n\n## Building\n\nStarting from ROS 2 Iron Irwini, the LTTng tracer is a ROS 2 dependency.\nTherefore, ROS 2 can be traced out-of-the-box on Linux; this package does not need to be re-built.\nThe following `rmw` implementations are supported:\n\n* `rmw_connextdds`\n* `rmw_cyclonedds_cpp`\n* `rmw_fastrtps_cpp`\n* `rmw_fastrtps_dynamic_cpp`\n* `rmw_zenoh_cpp`\n\nTo make sure that the instrumentation and tracepoints are available:\n\n```\n$ source /opt/ros/rolling/setup.bash  # With a binary install\n$ source ./install/setup.bash  # When building from source\n$ ros2 run tracetools status\nTracing enabled\n```\n\nA ROS 2 installation only includes the LTTng userspace tracer (LTTng-UST), which is all that is needed to trace ROS 2.\nTo trace the Linux kernel, the [LTTng kernel tracer](https://lttng.org/docs/v2.13/#doc-tracing-the-linux-kernel) must be installed separately:\n\n```\n$ sudo apt-get update\n$ sudo apt-get install lttng-modules-dkms\n```\n\nFor more information about LTTng, [refer to its documentation](https://lttng.org/docs/v2.13/).\n\n### Disabling the tracer at runtime\n\nTo avoid loading the tracer at runtime (and therefore disable all instrumentation), set the `TRACETOOLS_RUNTIME_DISABLE` environment variable to `1`:\n\n```\n$ export TRACETOOLS_RUNTIME_DISABLE=1\n$ ros2 run tracetools status\nTracing disabled\n```\n\n### Removing the instrumentation\n\nTo build and remove all instrumentation, use `TRACETOOLS_DISABLED`:\n\n```\n$ colcon build --cmake-args -DTRACETOOLS_DISABLED=ON\n```\n\nThis will remove all instrumentation from the core ROS 2 packages, and thus they will not depend on or link against the shared library provided by the [`tracetools` package](#tracetools).\nThis also means that LTTng is not required at build-time or at runtime.\n\n### Excluding tracepoints\n\nAlternatively, to only exclude the actual tracepoints, use `TRACETOOLS_TRACEPOINTS_EXCLUDED`:\n\n```\n$ colcon build --packages-select tracetools --cmake-clean-cache --cmake-args -DTRACETOOLS_TRACEPOINTS_EXCLUDED=ON\n```\n\nThis will keep the instrumentation but remove all tracepoints.\nThis also means that LTTng is not required at build-time or at runtime.\nThis option can be useful, since tracepoints can be added back in or removed by simply replacing/re-building the shared library provided by the [`tracetools` package](#tracetools).\n\n## What is tracing?\n\nSoftware *tracing* is a method of collecting low-level runtime data to understand a system's execution.\nThis is achieved by *instrumenting* the code using *tracepoints*, for example in ROS 2, the Linux kernel, or any other application.\nWhen a tracepoint is executed, it generates information that is collected by a *tracer* into a *trace*.\nTracers are usually low-overhead to avoid affecting the execution.\nTraces can then be analyzed to help understand the execution, fix bugs, improve performance, etc.\nWhile *logs* are typically high-level enough for a user to read and understand, trace data is low-level \u0026 high-rate and therefore usually needs to be processed to be useful.\n\nFor more information, see the following introductions on tracing:\n\n* [LTTng tracer documentation](https://lttng.org/docs/v2.13/#doc-what-is-tracing)\n* [Tracing tutorial](https://github.com/tuxology/tracevizlab/tree/master/labs/001-what-is-tracing#what-is-tracing)\n* [Eclipse Trace Compass (trace analysis tool) documentation](https://archive.eclipse.org/tracecompass/doc/stable/org.eclipse.tracecompass.doc.user/Overview.html#About_Tracing)\n\n## Tracing\n\nBy default, trace data will not be generated, and thus these packages will have virtually no impact on execution.\nLTTng has to be configured for tracing.\nThe packages in this repo provide two options: a [command](#trace-command) and a [launch file action](#launch-file-trace-action).\n\n\u003e [!NOTE]\n\u003e Tracing must be started before the application is launched.\n\u003e Metadata is recorded during the initialization phase of the application.\n\u003e This metadata is needed to understand the rest of the trace data, so if tracing is started after the application started executing, then the trace data might be unusable.\n\u003e For more information, refer to the [design document](./doc/design_ros_2.md#general-guidelines).\n\u003e The [launch file action](#launch-file-trace-action) is designed to automatically start tracing before the application launches.\n\nThe tracing directory can be configured using command/launch action parameters, or through environment variables with the following logic:\n\n* Use `$ROS_TRACE_DIR` if `ROS_TRACE_DIR` is set and not empty.\n* Otherwise, use `$ROS_HOME/tracing`, using `~/.ros` for `ROS_HOME` if not set or if empty.\n\nAdditionally, **if you're using kernel tracing with a non-root user, make sure that the [`tracing` group exists and that your user is added to it](https://lttng.org/docs/v2.13/#doc-tracing-group)**.\n\n```\n# Create group if it doesn't exist\n$ sudo groupadd -r tracing\n# Add user to the group\n$ sudo usermod -aG tracing $USER\n```\n\n### Trace command\n\nThe first option is to use the `ros2 trace` command.\n\n```\n$ ros2 trace\n```\n\nBy default, it will enable all ROS 2 tracepoints.\nThe trace will be written to `~/.ros/tracing/session-YYYYMMDDHHMMSS`.\nRun the command with `-h` for more information.\n\nThe `ros2 trace` command requires user interaction to start and then stop tracing.\nTo trace without user interaction (e.g., in scripts), or for finer-grained tracing control, the following sub-commands can be used:\n\n```\n$ ros2 trace start session_name   # Configure tracing session and start tracing\n$ ros2 trace pause session_name   # Pause tracing after starting\n$ ros2 trace resume session_name  # Resume tracing after pausing\n$ ros2 trace stop session_name    # Stop tracing after starting or resuming\n```\n\nRun each command with `-h` for more information.\n\nYou must [install the kernel tracer](#building) if you want to enable [kernel](https://lttng.org/docs/v2.13/#doc-tracing-the-linux-kernel) events (using the `-k`/`--kernel-events` option) or syscalls (using the `--syscalls` option).\nIf you have installed the kernel tracer, use kernel tracing, and still encounter an error here, make sure to [add your user to the `tracing` group](#tracing).\n\n### Launch file trace action\n\nAnother option is to use the `Trace` action in a Python, XML, or YAML launch file along with your `Node` action(s).\nThis way, tracing automatically starts when launching the launch file and ends when it exits or when terminated.\n\n```\n$ ros2 launch tracetools_launch example.launch.py\n```\n\nThe `Trace` action will also set the `LD_PRELOAD` environment to preload [LTTng's userspace tracing helper(s)](https://lttng.org/docs/v2.13/#doc-prebuilt-ust-helpers) if the corresponding event(s) are enabled.\nFor more information, see [this example launch file](./tracetools_launch/launch/example.launch.py) and the [`Trace` action](./tracetools_launch/tracetools_launch/action.py).\n\nYou must [install the kernel tracer](#building) if you want to enable [kernel](https://lttng.org/docs/v2.13/#doc-tracing-the-linux-kernel) events (`events_kernel` in Python, `events-kernel` in XML or YAML) or syscalls (`syscalls` in Python, XML, or YAML).\nIf you have installed the kernel tracer, use kernel tracing, and still encounter an error here, make sure to [add your user to the `tracing` group](#tracing).\n\n## Design\n\nSee the [design document](./doc/design_ros_2.md).\n\n## Real-time\n\nLTTng-UST, the current default userspace tracer used for [tracing ROS 2](#overview), was designed for real-time production applications.\nIt is a low-overhead tracer with many important real-time compatible features:\n\n* userspace tracer completely implemented in userspace, independent from the kernel\n* reentrant, thread-safe, signal-safe, non-blocking\n* no system calls in the fast path\n* no copies of the trace data\n\nHowever, some settings need to be tuned for it to be fully real-time safe and for performance to be optimal for your use-case:\n\n* timers[^rt-1]: use [read timer](https://lttng.org/docs/v2.13/#doc-channel-read-timer) to avoid a write(2) call\n* sub-buffer[^rt-1] count and size:\n    * see [documentation](https://lttng.org/docs/v2.13/#doc-channel-subbuf-size-vs-subbuf-count) for sub-buffer count and size tuning tips based on your use-case\n    * minimize sub-buffer count to minimize sub-buffer switching overhead\n* one-time memory allocation/lock/syscall per thread:\n    * usually done the first time a tracepoint is executed within a thread for URCU thread registration, but registration can be manually performed to force it to be done during your application's initialization\n    * see [this LTTng mailing list message](https://lists.lttng.org/pipermail/lttng-dev/2019-November/029409.html)\n\n[^rt-1]: this setting cannot currently be set through the [`Trace` launch file action](#launch-file-trace-action) or the [`ros2 trace` command](#trace-command), see [#20](https://github.com/ros2/ros2_tracing/issues/20)\n\nFor further reading:\n\n* [LTTng documentation](https://lttng.org/docs/v2.13/)\n* [Combined Tracing of the Kernel and Applications with LTTng](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.641.1965\u0026rep=rep1\u0026type=pdf#page=87): LTTng-UST architecture and design goals (section 3)\n* [Survey and Analysis of Kernel and Userspace Tracers on Linux: Design, Implementation, and Overhead](https://dl.acm.org/doi/abs/10.1145/3158644): LTTng-UST overhead and design compared to other kernel and userspace tracers (table 6: average latency overhead per tracepoint of 158 ns)\n\nThe LTTng kernel tracer has a similar implementation, but is separate from the userspace tracer.\n\n## Packages\n\n### lttngpy\n\nPackage containing `liblttng-ctl` Python bindings.\n\n### ros2trace\n\nPackage containing a `ros2cli` extension to enable tracing.\n\n### tracetools\n\nLibrary to support instrumenting ROS packages, including core packages.\n\nThis package claims to be in the **Quality Level 1** category, see the [Quality Declaration](./tracetools/QUALITY_DECLARATION.md) for more details.\n\nSee the [API documentation](https://docs.ros.org/en/rolling/p/tracetools/).\n\n### tracetools_launch\n\nPackage containing tools to enable tracing through launch files.\n\n### tracetools_read\n\nPackage containing tools to read traces.\n\n### tracetools_test\n\nPackage containing tools for tracing-related tests.\n\n### tracetools_trace\n\nPackage containing tools to enable tracing.\n\n### test_ros2trace\n\nPackage containing system tests for `ros2trace`.\n\n### test_tracetools\n\nPackage containing unit and system tests for `tracetools`.\n\n### test_tracetools_launch\n\nPackage containing system tests for `tracetools_launch`.\n\n## Analysis\n\nSee [`tracetools_analysis`](https://github.com/ros-tracing/tracetools_analysis).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fros2%2Fros2_tracing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fros2%2Fros2_tracing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fros2%2Fros2_tracing/lists"}