Set up a local capture on a device using the command-line

Run gatord on the command-line to capture data locally on a device when you are experiencing network problems, or when you are running headless Continuous Integration (CI) testing.

About this task

This topic explains how to set up a local capture on a device using the command-line. For instructions on how to set up a local capture on a device using the Streamline GUI, see Set up a local capture on a device using the Streamline GUI.

Procedure

  1. Create a configuration.xml file.

    Modify an existing configuration.xml, or create a new one. To learn more about creating a new configuration.xml file, see Creating a configuration.xml file.

  2. Create the session.xml file with your required arguments. For example:

    <?xml version="1.0" encoding="UTF-8"?>
<session version="2" call_stack_unwinding="yes" parse_debug_info="yes" resolution_mode="normal" buffer_mode="streaming" sample_rate="normal" duration="0" target_address="x.x.x.x" live_rate="100" stop_gator="no">
   <image path="<path/to/image>"/>
   <energy_capture version="1" command_path="<path/to/>caiman.exe" type="none">
      <channel id="0" resistance="20" power="yes"/>
   </energy_capture>
</session>

    You can set the following arguments:

    call_stack_unwinding="yes|no"

    Records call stacks to increase the amount of raw data that the device sends to the host.

    To support call stack unwinding for binaries that are created using GCC or LLVM, enable frame pointers using the -fno-omit-frame-pointer compiler option.

    For Arm®v7 software applications, you must also use the -marm option to disable the Thumb® instruction set.

    parse_debug_info="yes|no"

    Processes DWARF debug information and line numbers for a more detail in your capture session.

    To process debug information, you must have built the image using the -g compiler option.

    resolution_mode="summary|normal|high|ultrahigh"

    Controls the resolution used to analyze and visualize the data after it has been captured.

    Higher resolutions allow you to view data with a finer time granularity, but result in longer analysis times and higher memory usage.

    buffer_mode="streaming|large|medium|small"

    • large: 16M

    • medium: 4M

    • small: 1M

    • streaming: Enables Live view and streaming of device data directly to your host during online capture.

    sample_rate="high|low|none"

    • high: Uses a sample frequency of 10kHz and enhances visibility, but also incurs an increase in overhead.

    • low: Uses a sample frequency of 100Hz. Use low if the device is slow or heavily loaded.

    • none: Disables periodic sampling. Use none if you have the lowest level of intrusion on your code. Any report columns that rely on sampling show zero values.

      Note

      none still samples on context switches.

    duration=""

    To set a duration for the capture, enter the time that you want the capture session to last, either in seconds or in minutes and seconds.

    For example, use 60 to set a capture session of 60 seconds, or use 1:20 to set a capture session of 1 minute and 20 seconds.

    If you do not enter a duration, the capture session continues until you stop it manually.

    If you do not specify buffer_mode="streaming", the capture session continues until the buffer is full.

    use_efficient_ftrace="yes|no"

    The Live view does not update charts that use Ftrace data, but the data is in the analyzed report.

  3. Run gatord with your configuration.xml and session.xml files, and include the appropriate options for root or non-root devices:

    ./gatord -s session.xml -c configuration.xml <options> -o <capture-filename>.apc

Results

gatord captures a profile of all the processes running on your device, and writes the data to the specified location.

Next steps

Copy the .apc directory into the Streamline capture directory. This directory is usually <Home>/<User>/Documents/Streamline.