{"id":23305670,"url":"https://github.com/ros-tracing/tracetools_analysis","last_synced_at":"2025-08-22T10:30:46.212Z","repository":{"id":52525530,"uuid":"236339333","full_name":"ros-tracing/tracetools_analysis","owner":"ros-tracing","description":"Utilities for analyzing trace data from ROS 2 systems generated by the ros2_tracing packages.","archived":false,"fork":false,"pushed_at":"2024-06-26T19:24:00.000Z","size":2841,"stargazers_count":15,"open_issues_count":0,"forks_count":10,"subscribers_count":3,"default_branch":"rolling","last_synced_at":"2024-06-27T23:09:29.940Z","etag":null,"topics":["ros","ros2","ros2-tracing","trace-analysis","tracetools-analysis","tracing"],"latest_commit_sha":null,"homepage":"","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/ros-tracing.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2020-01-26T16:23:30.000Z","updated_at":"2024-06-26T19:23:47.000Z","dependencies_parsed_at":"2024-05-31T17:21:10.285Z","dependency_job_id":"dcb1ac4d-808f-4b82-8827-0ed00f7b3067","html_url":"https://github.com/ros-tracing/tracetools_analysis","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros-tracing%2Ftracetools_analysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros-tracing%2Ftracetools_analysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros-tracing%2Ftracetools_analysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ros-tracing%2Ftracetools_analysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ros-tracing","download_url":"https://codeload.github.com/ros-tracing/tracetools_analysis/tar.gz/refs/heads/rolling","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230582885,"owners_count":18248672,"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","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":["ros","ros2","ros2-tracing","trace-analysis","tracetools-analysis","tracing"],"created_at":"2024-12-20T12:13:24.538Z","updated_at":"2024-12-20T12:13:26.225Z","avatar_url":"https://github.com/ros-tracing.png","language":"Python","funding_links":[],"categories":["ROS2"],"sub_categories":["Dev Tools"],"readme":"# tracetools_analysis\n\n\u003c!-- [![GitHub CI](https://github.com/ros-tracing/tracetools_analysis/actions/workflows/test.yml/badge.svg?branch=rolling)](https://github.com/ros-tracing/tracetools_analysis/actions/workflows/test.yml) --\u003e\n[![codecov](https://codecov.io/gh/ros-tracing/tracetools_analysis/branch/rolling/graph/badge.svg)](https://codecov.io/gh/ros-tracing/tracetools_analysis)\n\nAnalysis tools for [`ros2_tracing`](https://github.com/ros2/ros2_tracing).\n\n**Note**: make sure to use the right branch, depending on the ROS 2 distro: [use `rolling` for Rolling, `humble` for Humble, etc.](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Developer-Guide.html)\n\n## Trace analysis\n\nAfter generating a trace (see [`ros2_tracing`](https://github.com/ros2/ros2_tracing#tracing)), we can analyze it to extract useful execution data.\n\n### Commands\n\nThen we can process a trace to create a data model which could be queried for analysis.\n\n```shell\n$ ros2 trace-analysis process /path/to/trace/directory\n```\n\nNote that this simply outputs lightly-processed ROS 2 trace data which is split into a number of pandas `DataFrame`s.\nThis can be used to quickly check the trace data.\nFor real data processing/trace analysis, see [*Analysis*](#analysis).\n\nSince CTF traces (the output format of the [LTTng](https://lttng.org/) tracer) are very slow to read, the trace is first converted into a single file which can be read much faster and can be re-used to run many analyses.\nThis is done automatically, but if the trace changed after the file was generated, it can be re-generated using the `--force-conversion` option.\nRun with `--help` to see all options.\n\n### Analysis\n\nThe command above will process and output raw data models.\nWe need to actually analyze the data and display some results.\nWe recommend doing this in a Jupyter Notebook, but you can do this in a normal Python file.\n\n```shell\n$ jupyter notebook\n```\n\nNavigate to the [`analysis/`](./tracetools_analysis/analysis/) directory, and select one of the provided notebooks, or create your own!\n\nFor example:\n\n```python\nfrom tracetools_analysis.loading import load_file\nfrom tracetools_analysis.processor import Processor\nfrom tracetools_analysis.processor.cpu_time import CpuTimeHandler\nfrom tracetools_analysis.processor.ros2 import Ros2Handler\nfrom tracetools_analysis.utils.cpu_time import CpuTimeDataModelUtil\nfrom tracetools_analysis.utils.ros2 import Ros2DataModelUtil\n\n# Load trace directory or converted trace file\nevents = load_file('/path/to/trace/or/converted/file')\n\n# Process\nros2_handler = Ros2Handler()\ncpu_handler = CpuTimeHandler()\n\nProcessor(ros2_handler, cpu_handler).process(events)\n\n# Use data model utils to extract information\nros2_util = Ros2DataModelUtil(ros2_handler.data)\ncpu_util = CpuTimeDataModelUtil(cpu_handler.data)\n\ncallback_symbols = ros2_util.get_callback_symbols()\ncallback_object, callback_symbol = list(callback_symbols.items())[0]\ncallback_durations = ros2_util.get_callback_durations(callback_object)\ntime_per_thread = cpu_util.get_time_per_thread()\n# ...\n\n# Display, e.g., with bokeh, matplotlib, print, etc.\nprint(callback_symbol)\nprint(callback_durations)\n\nprint(time_per_thread)\n# ...\n```\n\nNote: bokeh has to be installed manually, e.g., with `pip`:\n\n```shell\n$ pip3 install bokeh\n```\n\n## Design\n\nSee the [`ros2_tracing` design document](https://github.com/ros2/ros2_tracing/blob/rolling/doc/design_ros_2.md), especially the [*Goals and requirements*](https://github.com/ros2/ros2_tracing/blob/rolling/doc/design_ros_2.md#goals-and-requirements) and [*Analysis*](https://github.com/ros2/ros2_tracing/blob/rolling/doc/design_ros_2.md#analysis) sections.\n\n## Packages\n\n### ros2trace_analysis\n\nPackage containing a `ros2cli` extension to perform trace analysis.\n\n### tracetools_analysis\n\nPackage containing tools for analyzing trace data.\n\nSee the [API documentation](https://docs.ros.org/en/rolling/p/tracetools_analysis/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fros-tracing%2Ftracetools_analysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fros-tracing%2Ftracetools_analysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fros-tracing%2Ftracetools_analysis/lists"}