diff --git a/README.md b/README.md index f74bf16..522d3bb 100644 --- a/README.md +++ b/README.md @@ -11,57 +11,70 @@ After generating a trace (see [`ros2_tracing`](https://gitlab.com/ros-tracing/ro ### Commands -Since CTF traces (the output format of the [LTTng](https://lttng.org/) tracer) are very slow to read, we first convert them into a single file which can be read much faster. - -``` -$ ros2 trace-analysis convert /path/to/trace/directory -``` - -Then we can process it to create a data model which could be queried for analysis. +Then we can process a trace to create a data model which could be queried for analysis. ``` $ ros2 trace-analysis process /path/to/trace/directory ``` -### Jupyter +Note that this simply outputs lightly-processed ROS 2 trace data which is split into a number of pandas `DataFrame`s. +This can be used to quickly check the trace data. +For real data processing/trace analysis, see [*Analysis*](#analysis). -The last command will process and output the raw data models, but to actually display results, process and analyze using a Jupyter Notebook. +Since 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. +This is done automatically, but if the trace changed after the file was generated, it can be re-generated using the `--force-conversion` option. +Run with `--help` to see all options. + +### Analysis + +The command above will process and output raw data models. +We need to actually analyze the data and display some results. +We recommend doing this in a Jupyter Notebook, but you can do this in a normal Python file. ```shell $ jupyter notebook ``` -Then navigate to the [`analysis/`](./tracetools_analysis/analysis/) directory, and select one of the provided notebooks, or create your own! +Navigate to the [`analysis/`](./tracetools_analysis/analysis/) directory, and select one of the provided notebooks, or create your own! For example: ```python -from tracetools_analysis import loading -from tracetools_analysis import processor -from tracetools_analysis import utils +from tracetools_analysis.loading import load_file +from tracetools_analysis.processor import Processor +from tracetools_analysis.processor.cpu_time import CpuTimeHandler +from tracetools_analysis.processor.ros2 import Ros2Handler +from tracetools_analysis.utils.cpu_time import CpuTimeDataModelUtil +from tracetools_analysis.utils.ros2 import Ros2DataModelUtil # Load trace directory or converted trace file -events = loading.load_file('/path/to/trace/or/converted/file') +events = load_file('/path/to/trace/or/converted/file') # Process -ros2_handler = processor.Ros2Handler() -cpu_handler = processor.CpuTimeHandler() +ros2_handler = Ros2Handler() +cpu_handler = CpuTimeHandler() -processor.Processor(ros2_handler, cpu_handler).process(events) +Processor(ros2_handler, cpu_handler).process(events) # Use data model utils to extract information -ros2_util = utils.ros2.Ros2DataModelUtil(ros2_handler.data) -cpu_util = utils.cpu_time.CpuTimeDataModelUtil(cpu_handler.data) +ros2_util = Ros2DataModelUtil(ros2_handler.data) +cpu_util = CpuTimeDataModelUtil(cpu_handler.data) -callback_durations = ros2_util.get_callback_durations() +callback_symbols = ros2_util.get_callback_symbols() +callback_object, callback_symbol = list(callback_symbols.items())[0] +callback_durations = ros2_util.get_callback_durations(callback_object) time_per_thread = cpu_util.get_time_per_thread() # ... -# Display, e.g. with bokeh or matplotlib +# Display, e.g., with bokeh, matplotlib, print, etc. +print(callback_symbol) +print(callback_durations) + +print(time_per_thread) # ... ``` -Note: bokeh has to be installed manually, e.g. with `pip`: +Note: bokeh has to be installed manually, e.g., with `pip`: ```shell $ pip3 install bokeh