The Streamline daemon, gatord, has two modes of operation, daemon mode and local capture mode. It’s normally used in daemon mode to capture and send data over a network or USB connection from the target system to the host computer. Local capture mode is used when it’s not possible to send live data back to the host. With local capture mode data is stored on the target system and the files are later copied to the host computer for analysis by Streamline.
After writing Streamline performance analyzer for Android application profiling it turns out some Android devices restrict the use of TCP sockets and this causes gatord to fail in daemon mode. The problem is device specific and is not related to the Android version. A future version of Streamline will provide a better solution to the problem, but until then local capture mode can be used.
If you followed the article and experienced the error below, it indicates the Android device doesn’t allow a TCP connection. Local capture mode can be used instead to profile the application.
$ adb shell run-as org.supertuxkart.stk_dbg ./gatord --wait-process org.supertuxkart.stk_dbg Streamline gatord version 670 (Streamline v6.7) Error creating server TCP socket
To capture data on the device two files are needed. A session.xml file and a configuraton.xml file. A review of the gatord command line arguments is also useful to get started.
To create the two xml files, put gatord in /data/local/tmp and make a normal Streamline connection. This is possible because the adb shell permissions are different than the permissions of the user id for the application to be profiled. I will continue with the SuperTuxKart application, but change the package name as needed for the application you would like to profile.
$ adb push $DS5_HOME/sw/streamline/bin/arm/gatord /data/local/tmp $ adb shell /data/local/tmp/gatord --wait-process org.supertuxkart.stk_dbg
Connect Streamline by clicking the “Browse for target” button (eyeball). Use the Counter Configuration button (chip) to select the counters. As long as the --wait-process flag was used the CPU counters should be visible so they can be selected. Without the flag the CPU counters won't appear. This will generate a configuration.xml file in /data/local/tmp on the Android device.
To get the session.xml file use the Capture & Analysis options button (gear) and click Export at the bottom. This will launch a dialog to save the session.xml on the host computer.
Both files need to go in the data directory for the application to be profiled. The configuration.xml is already on the device, but it needs to be copied to the application data directory.
$ adb shell run-as org.supertuxkart.stk_dbg cp /data/local/tmp/configuration.xml configuration.xml
The session.xml needs to be pushed from the host to the application data directory on the device. This is a good time to optionally edit the session.xml to set values such as the duration of the capture, but there is no requirement to change anything.
$ adb push session.xml /data/local/tmp $ adb shell run-as org.supertuxkart.stk_dbg cp /data/local/tmp/session.xml session.xml
Next, a local capture can be started. Make sure to kill the previously run gatord before starting to capture the actual application profiling data.
$ adb shell $ run-as org.supertuxkart.stk_dbg $ ./gatord -c configuration.xml -s session.xml -o c1.apc --wait-process org.supertuxkart.stk_dbg
Use Ctrl-c to kill the gatord if needed before the duration expires. I found that running gatord using adb shell on the host is problematic because Ctrl-c does not terminate gatord and the capture file is not closed out. For this reason I recommend to use adb shell to connect and then run gatord directly on the device and Ctrl-c will cause a clean exit of the daemon. If the application being profiled exits then gatord will also exit.
The session.xml is not actually required if all default values are used. The -t option for gatord can be used to collect a profile for some number of seconds.
$ ./gatord -c configuration.xml -o c2.apc -t 120 --wait-process org.supertuxkart.stk_dbg
The next step is to copy the captured data from the Android device back to the host computer and open it in Streamline. Depending on the device there are a few ways that may or may not work.
The first method to try is to pull the data from /data/local/tmp using adb.
$ adb shell $ run-as org.supertuxkart.stk_dbg $ cp -r c1.apc /data/local/tmp
Back on the host computer:
$ adb pull /data/local/tmp/c1.apc
If /data/local/tmp doesn't work try the sdcard. This works for some Android devices.
$ adb shell $ run-as org.supertuxkart.stk_dbg $ cp -r c1.apc /mnt/sdcard
$ adb pull /mnt/sdcard/c1.apc
For some devices both /data/local/tmp and the sdcard fail due to lack of write permission from the application user id, but Android Studio can be used instead.
Start Android Studio and open the Device File Explorer:
$ studio.sh &
View -> Tool Windows -> Device File Explorer
Find the capture directories in /data/data/org.supertuxkart.stk_dbg and right click them to select “Save as”. Navigate to a path on the host computer and the c1.apc directory will be saved.
There are two ways to help Streamline find the capture directories. One is to add a new directory using the Edit Locations button (folder) and then use the New button to navigate to the directory with the capture data (c1.apc). This tells Streamline to look here also. Streamline is looking for the directory name with the capture files in it. It's not looking for a specific file to open.
A second way is to copy the directories to the default location. On Linux this is $HOME/Documents/Streamline and C:\Users\<user_name>\Documents\Streamline on Windows.
If Streamline finds and identifies the data directories, the capture shows up in the Streamline Data tab. Just right click it and select Analyze. For source level information click the Add ELF image and navigate to the object file with debugging symbols.
For the example SuperTuxKart application the file to load is:
$HOME/kart/stk-code/android/obj/local/armeabi-v7a/libmain.so
Currently, some Android devices don’t allow the Streamline gator daemon to collect performance analysis data in in daemon mode. The gator daemon can be used in local capture mode to overcome this error. A local capture will store the collected data on the Android device and it can be copied back to the host computer for analysis by Streamline. A future version of Streamline will provide a way to use daemon mode on devices which prohibit the TCP socket connection by using a different type of socket connection. Please share your successes or failures with Streamline for the devices you are using. If you haven't tried it yet, download DS-5 using the button below and request a trial license.
Get started with the DS-5 Development Studio