gatord command-line options

gatord must be running before you can capture trace data. The command-line options configure how gatord captures events and how it communicates with Streamline running on your host.

gatord has two modes of operation:

Daemon mode (the default mode)

Sends captured events to a host running Streamline.

Local capture mode

Writes the capture to a file then exits.

To enable this mode, specify an output directory with the --output flag.

Arguments available to all modes:

gatord arguments available to all modes
Option Description
-h, --help Lists all the available gatord command-line options.
-c, --config-xml <config_xml> Specify the path and filename of the configuration.xml file that defines the capture options. In daemon mode, the list of counters is written to this file. In local capture mode, the list of counters is read from this file.
-e, --events-xml <events_xml> Specify the path and filename of the events.xml file. events.xml defines all the counters that Streamline collects during the capture session.
-E, --append-events-xml <events_xml> Specify the path and filename of the events.xml file to append.
-P, --pmus-xml <pmu_xml> Specify the path and filename of the pmu.xml file to append.
-v, --version Print version information.
-d, --debug Enable debug messages.
-A, --app <cmd> <args...> Specify the command to execute when the capture starts. This argument must be the last argument that is passed to gatord. All subsequent arguments are passed to the launched application.
-k, --exclude-kernel <yes|no> Specify whether to filter out kernel events from the perf results.
-S, --system-wide <yes|no>

Specify whether to capture the whole system.

In daemon mode, no is only applicable when --allow-command is specified. In this mode, you must enter a command in the Start view.

Defaults to yes, unless --app, --pid, or --wait-process is specified.
-u, --call-stack-unwinding <yes|no> Enable or disable call stack unwinding. Defaults to yes.
-r, --sample-rate <none|low|normal|high>

Specify the sample rate for the capture. The frequencies for each sample rate are:

  • high = 10kHz

  • normal = 1kHz

  • low = 100Hz

  • none = the lowest possible rate

Defaults to normal.
-t, --max-duration <s> Specify the maximum duration that the capture can run for in seconds. Defaults to 0, which means unlimited.
-f, --use-efficient-ftrace <yes|no> Enable efficient ftrace data collection mode. Defaults to yes.
-w, --app-cwd <path> Specify the working directory for the application that gatord launches. Defaults to the current directory.
-x, --stop-on-exit <yes|no> Stop the capture when the launched application exits. Defaults to no, unless --app, --pid, or --wait-process is specified.
-Q, --wait-process <command> Wait for a process that matches the specified command to launch before starting the capture. Attach to the specified process and profile it.
-Z, --mmap-pages <n> The maximum number of pages to map per mmaped perf buffer is equal to <n+1>. n must be a power of two.
-O, --disable-cpu-onlining <yes|no> To not switch on CPU cores that are offline to read their information. This option is useful for kernels that fail to handle this action correctly, for example they reboot the system. Defaults to no.
-F, --spe-sample-rate <n> Specify the SPE periodic sampling rate. The rate, <n>, is the number of operations between each sample, and must be a nonzero positive integer. The hardware specifies the minimum rate. Values below this threshold are ignored and the hardware minimum is used instead.
-L, --capture-log Enable to generate a log file for the capture in the capture's directory, as well as sending the logs to stderr. If you are using the streamline_me.py script, gator is launched with --capture-log enabled by default.
--smmuv3-model <model_id>|<iidr> Specify the SMMUv3 model. You can specify the model ID string directly, such as mmu-600, or the hex value representation for the model's IIDR number either fully, such as 4832243b, or partially, such as 483_43b.
-Y, --off-cpu-time <yes|no> Collect Off-CPU time statistics. Detailed statistics require root permission.
-I, --inherit <yes|no|poll>

When profiling an application, gatord monitors all subsequent threads and child processes. Specify no to monitor only the initial thread of the application. Specify poll to periodically look for new processes or threads.

Note

Per-function metrics are only supported in system-wide mode, or when --inherit is set to no or poll. The default is yes.
-N, --num-pmu-counters <n>

Override the number of programmable PMU counters that are available.

This option reduces the number of programmable PMU counters available for profiling. Use this option when the default is incorrect, or because some programmable counters are unavailable because they are consumed by the OS, or other processes, or by a hypervisor.

Note

The Arm PMU typically exposes 6 programmable counters, and one fixed function cycle counter. This argument assumes the fixed cycle counter is not part of the reduced set of counters. If your target exposes 2 programmable counters and the fixed cycle counter, then 2 is passed for the value of <n>. However, if your target exposes 2 programmable counters and no fixed cycle counter, then 1 is passed for the value of <n>.

Arguments available on Android devices only:

gatord arguments available on Android devices only
Option Description

  • l, --android-pkg <pkg>

 Profiles the specified android package. Waits for the package app to launch before starting a capture unless --android-activity is specified.

  • m, --android-activity <activity>

 Launch the specified activity of a package and profile its process. You must also specify --android-pkg.

  • n, --activity-args <arguments>

 Launch the specified activity of a package and profile its process with the supplied activity manager (am) arguments. You must also specify --android-pkg and --android-activity.

Arguments available in daemon mode only:

gatord arguments available in daemon mode only
Option Description
-p, --port <port_number>|uds

Set the port number that gatord uses to communicate with the host. The default is 8080.

If you use the argument uds, the TCP socket is disabled and an abstract Unix domain socket is created. This socket is named streamline-data. If you use Android, creating a Unix domain socket is useful because gatord is usually prevented from creating a TCP server socket.

Alternatively, you can connect to localhost:<local_port> in Streamline using:

adb forward tcp:<local_port> localabstract:streamline-data
-a, --allow-command

Allows you to run a command on the device during profiling. The command is specified in the Start view.

Note

If you use this option, an unauthenticated user could run arbitrary commands on the device using Streamline.

Arguments available to local capture mode only:

gatord arguments available to local capture mode only
Option Description
-s, --session-xml <session_xml> Specify the session.xml file that the configuration is taken from. Any additional arguments override values that are specified in this file.
-o, --output <apc_dir> Specify the path and filename of the output directory for a local capture. The directory path will be appended with the extension .apc if it is not already the case.
-i, --pid <pids...> A comma-separated list of process IDs to profile.
-C, --counters <counters>

A comma-separated list of counters to enable. You can specify this option multiple times. An event code and a slot identify most hardware counters. To specify the counter for a particular slot, pass:

--counters <device>_cnt<s>:<e>

Where:

  • <device> is the prefix that identifies the device type.

  • <s> is the slot number.

  • <e> is the event code.
-X, --spe <id>[:events=<indexes>][:ops=<types>][:min_latency=<lat>]

Enable the Statistical Profiling Extension (SPE).

Where:

  • <id> is the name of the SPE properties that are specified in the events.xml or pmus.xml file. It uniquely identifies the available events and counters for the SPE hardware.

  • <indexes> is a comma-separated list of event indexes to filter the sampling by. A sample is only recorded if all events are present.

  • <types> is a comma-separated list of operation types to filter the sampling by. If a sample is any of the types in <types>, it is recorded. Valid types are LD for load, ST for store and B for branch.

  • <lat> is the minimum latency. A sample is only recorded if its latency is greater than or equal to this value. The valid range is [0,4096].

Argument usage examples

  • Use --pmus-xml and --append-events-xml to add support for a new PMU without having to rebuild gatord.

    --pmus-xml specifies an XML file that defines a new PMU to add to the list of PMUs that gatord has built-in support for. The list of built-in PMUs is defined in pmus.xml, which is in the gatord source directory.

    --append-events-xml specifies an XML file that defines one or more event counters to append to the events.xml file. This option allows you to add new events to gatord without having to rebuild gatord or to entirely replace events.xml.

    The events.xml file must include the XML header and elements that are shown in the following example:

    <?xml version="1.0" encoding="UTF-8"?>
<events>
    <category name="Filesystem">
        <event counter="filesystem_loginuid" path="/proc/self/loginuid" title="loginuid" name="loginuid" description="loginuid"/>
    </category>
</events>

  • The Instructions Executed counter is configured in slot 0 as:

    --counters ARMv8_Cortex_A53_cnt0:0x08

    To configure the cycle counter, specify --counters <device>_ccnt. For example:

    --counters ARMv8_Cortex_A53_ccnt

    Other counters do not have event codes and are identified only by name. For example:

    --counters PERF_COUNT_SW_PAGE_FAULTS