docs/html/training/performance/battery/network/gather-data.jd

page.title=Collecting Network Traffic Data
trainingnavtop=true

@jd:body

<div id="tb-wrapper">
<div id="tb">

<h2>This lesson teaches you to </h2>
<ol>
  <li><a href="#tag-requests">Tag Network Requests</a></li>
  <li><a href="#build-type">Configure a Network Test Build Type</a></li>
  <li><a href="#deploy-apk">Deploy the Network Test APK</a></li>
  <li><a href="#network-tool">Run Network Traffic Tool</a></li>
</ol>

</div>
</div>

<p>
  The network traffic generated by an app can have a significant impact on the battery life of the
  device where it is running. In order to optimize that traffic, you need to both measure it and
  identify its source. Network requests can come directly from a user action, requests from your own
  app code, or from a server communicating with your app.
</p>

<p>
  The <a href="{@docRoot}tools/debugging/ddms.html#network">Network Traffic tool</a> (part of the
  DDMS tools) enables you to view how and when your app transfers data over a network.
</p>

<p>
  This lesson shows you how to measure and categorize network requests by tagging your source code,
  then shows you how to deploy, test and visualize your apps's network traffic.
</p>


<h2 id="tag-requests">Tag Network Requests</h2>

<p>
  Apps use the networking hardware on a device for various reasons. In order to properly optimize
  your app's use of networking resources, you must understand how frequently your app is using the
  network and for what reasons. For performance analysis purposes, you should break down use of
  network hardware into these categories:
</p>

<ul>
  <li>
    <strong>User-initiated network requests</strong> - Requests initiated by the user, such as a
    user request for an updated articles list in a news app.
  </li>

  <li>
    <strong>App-initiated network requests</strong> - Requests initiated within Android app code
    that are not used to immediately satisfy a user action, such as an app request to cache the
    text of unread articles in a news app.
  </li>

  <li>
    <strong>Server-initiated network requests</strong> - Requests initiated by a server to your app
    that are not used to immediately satisfy a user action, such as notification of a newly
    available article in a news app.
  </li>
</ul>

<p>
  This procedure shows you how to tag your app's source code with constants to categorize traffic
  as one of these three request types. The Network Traffic tool represents each type of traffic
  with a different color, so you can visualize and optimize each traffic stream separately.
  The technique described here reports network traffic based on the execution of threads in your
  app which you identify as a user, app or server source.
</p>

<ol>
  <li>In your app's development project, define three constants to represent the different types
    of network use:

<pre id="constants">
public static final int USER_INITIATED = 0x1000;
public static final int APP_INITIATED = 0x2000;
public static final int SERVER_INITIATED =0x3000;
</pre>
  </li>

  <li>Find networking code in your app by searching for the most common classes used for
    this purpose:
    <ol type="a">
      <li>In Android Studio, choose <strong>Edit &gt; Find &gt; Find in Path</strong>.</li>
      <li>Paste the following string into the <strong>Text to find</strong> field:<br>
        <code>extends GcmTaskService|extends JobService|extends
        AbstractThreadedSyncAdapter|HttpUrlConnection|Volley|Glide|HttpClient</code>
      </li>
      <li>Check <strong>Regular expression</strong>.</li>
      <li>Check <strong>File mask(s)</strong> and type <code>*.java</code>.</li>
      <li>Click the <strong>Find</strong> button.</li>
    </ol>
  </li>

<li>
  Based on your findings in the previous step, tag your app's use of network traffic by adding the
  {@link android.net.TrafficStats#setThreadStatsTag} method to each execution thread in your app
  that uses network resources, as shown in the following code example.

<pre>
if (BuildConfig.NETWORK-TEST && Build.VERSION.SDK_INT &gt;= 14) {
    try {
        TrafficStats.setThreadStatsTag(USER_INITIATED);
        // make network request using HttpClient.execute()
    } finally {
        TrafficStats.clearThreadStatsTag();
    }
}
</pre>

    <p class="note">
      <strong>Note:</strong> Ensure the tagging does not get into your production code by making
      inclusion of this code conditional, based on the build type used to generate the APK.
      In the example above, the <code>BuildConfig.NETWORK-TEST</code> field identifies this
      APK as a test version.
    </p>

  </li>
</ol>

<p class="note">
  <strong>Note:</strong> This technique for tagging network traffic from your app depends on
  how the APIs that you are using access and manage network sockets. Some networking libraries
  may not allow the {@link android.net.TrafficStats} utilities to tag traffic from your app.
</p>

<p>
  For more information about tagging and tracking network traffic with the Network Traffic tool,
  see <a href="http://tools.android.com/recent/detailednetworkusageinddms">Detailed Network Usage
  in DDMS</a>.
</p>


<h2 id="build-type">Configure a Network Test Build Type</h2>

<p>
  When you run performance tests, your APK should be as close as possible to the production
  build. In order to achieve this for your network testing, create a <code>network-test</code>
  build type, rather than using <code>debug</code> build type.
</p>

<ol>
  <li>Open your app in Android Studio.</li>
  <li>Create a debuggable build type for your network test by modifying your project's
    <code>build.gradle</code> file as shown in the following code example:

<pre>
android {
    ...
    buildTypes {
        debug {
            // debuggable true is default for the debug buildType
        }
        <strong>network-test {
            debuggable true
        }</strong>
    }
    ...
}
</pre>
  </li>
</ol>


<h2 id="deploy-apk">Deploy the Network Test APK</h2>

<p>
  To deploy the APK generated by the {@code network-test} build type configured in the previous
  proceedure:
</p>

<ol>
  <li>Check that <strong>Developer Options</strong> are enabled on your test device. For
  information about how to check and enable this option, see <a href=
  "{@docRoot}tools/device.html#developer-device-options">Using Hardware Devices</a>.
  </li>

  <li>Using a USB cable, connect your test device to your development computer.
  </li>

  <li>In Android Studio, select <strong>Build Variants</strong> on the left edge of the window.
  </li>

  <li>Click the <strong>Sync Project with Gradle Files</strong> button to populate the
  Build Variants list with <code>network-test</code> for the app module.
  </li>

  <li>Choose <code>network-test</code> from the list.
  </li>

  <li>Deploy the debuggable version of your app to your device by choosing
  <strong>Run</strong> &gt; <strong>Debug</strong>.
  </li>
</ol>


<h2 id="network-tool">Run Network Traffic Tool</h2>

<p>
  The Network Traffic tool in Android Studio helps you see how your app uses network resources
  in real time, while it is running.
</p>

<p>
  To improve the repeatability of your testing, you should start with a known initial state for
  your app by clearing app data. The following procedure includes a step that shows you how to
  clear <em>all</em> app data including previously cached data and networking data. This step
  puts your app back to a state where it must re-cache all previously cached data. Do not skip
  this step.
</p>

<p>
  To start the Network Traffic tool and visualize the network requests:
</p>

<ol>
  <li>Start the Network Traffic tool by launching Android Studio and choosing <strong>Tools &gt;
  Android &gt; Android Device Monitor</strong>. When asked, allow incoming network connections.
  </li>

  <li>In the Android Device Monitor window, click the <strong>DDMS</strong> button along the top
  and choose the <strong>Network Statistics</strong> tab. If you don't see this tab, widen the
  window and then try <strong>Window &gt; Reset Perspective</strong>.
  </li>

  <li>Select your app to debug from the list of debuggable apps on your device in the
    <strong>Devices</strong> tab, then click the <strong>Start</strong> button in the
    <strong>Network Statistics</strong> tab.

    <p class="note">
      <strong>Note:</strong> You may be prompted to <strong>Allow USB Debugging</strong> on your
      device. Select <strong>OK</strong> to allow debugging to proceed.
    </p>
  </li>

  <li>Clear your app data using the following adb command:
<pre class="no-pretty-print">
adb shell pm clear <em>package.name.of.app</em>
</pre>
  </li>

  <li>Start your app and run a testing plan that exercises your app's primary use cases. Your plan
    should also allow for app idle time, where the user is not interacting with the app, to allow
    app-initiated and server-initiated network access to occur.
  </li>

  <li>Repeat the test by clearing the app data and running your test plan again. You should repeat
    the test a few times to verify the repeatability of your performance data.
  </li>
</ul>
</ol>

<p>
  Use of tagging for network traffic helps you visually distinguish each request category by
  producing a different color for each network traffic in the Network Traffic tool, as shown in
  Figure 1.
</p>

<img src="{@docRoot}images/training/performance/network_traffic_colors.png" />
<p class="img-caption">
  <strong>Figure 1.</strong> Network traffic tagged for the three categories.
</p>