Skip to main content

Network inspection

Argent records the HTTP requests of the running app in a network log. The agent reads this log. The agent tells you which request the app sent, which response came back, and what the payload contains.

The agent finds a wrong endpoint name in the requests that the app sent

Capture layers​

Argent captures traffic in four layers.

LayerPlatformsContent
JS runtimeiOS, Android, VegaThe XMLHttpRequest calls, also from axios, and the fetch() calls of React Native and Expo
Native NSURLProtocoliOS, Mac appsThe URLSession requests, also from native modules. See the Limits section
Native OkHttpAndroidOkHttp requests from a debuggable app
Chrome DevTools ProtocolChromium and ElectronAll request types of the active tab, also documents and assets

Each layer captures the traffic in the process of the app. Argent does not use a proxy. Thus you do not install a certificate, and you can read HTTPS traffic directly.

The native layer does not change the cookies of the app. Each request sends and stores cookies with the cookie settings of the app session that sent it.

In React Native, the JS runtime layer records each request where the request leaves the JavaScript code. The JS runtime layer records the requests in these functions:

  • XMLHttpRequest. Axios and the fetch() function of React Native use XMLHttpRequest.
  • The fetch() function of Expo (expo/fetch), also when the app imports it directly. Expo SDK 56 and later use this function as the global fetch().
  • The network module of React Native, when a library sends its requests there itself. An example is react-native-fetch-api, which replaces the global fetch().

Argent records each request one time. A function of the app that wraps fetch() does not change the number of records. An app can keep a reference to fetch() from before the capture started. Argent also records the requests through this reference. Argent also records the requests of a library that the app installs after the capture started.

The type of a record is Fetch for the fetch() functions of React Native and Expo, and for a library that sends its requests to the network module of React Native. The type is XHR for the XMLHttpRequest calls of the app, also from axios. An XMLHttpRequest call that the app sends through a copy of send() from before the capture started has the type Fetch.

For the fetch() function of Expo, Argent records the body of a response when the app reads the body. Expo gives the body to one reader only. Thus Argent does not read a body while the request runs. After the request ends, Argent takes the body of an error response that the app did not read. Argent gives this body to the app when the app reads it.

Native code does not use these functions. For native code, use a native layer. In a react-native-macos app, the native NSURLProtocol layer also records the fetch() calls.

Native network capture on Android​

Argent calls the native OkHttp layer native network capture. Use a debuggable app on Android 9 or later. The app must run as arm64-v8a or x86_64.

Ask the agent to start native network capture. Argent attaches an in-app agent to the running app. The in-app agent connects to Argent a short time after the agent starts the capture. Thus the agent asks Argent again until Argent reports that the capture is ready. Then repeat the action that sends the request. Argent captures OkHttp traffic, including React Native requests, Fresco images, and Expo fetch().

Native network capture follows the app. When the agent launches or restarts the app, Argent attaches the in-app agent to the new process. The launch steps of an e2e test do the same. The launch waits until the capture is ready, for at most 5 seconds. If the capture is not ready after this time, Argent reads the reason from the log of the device. This step can add 3 seconds when adb does not answer. The result of the launch tells the agent if Argent attached the in-app agent. A process can also start in a different way, for example from a launcher tap, from a link, or after a crash. Argent attaches the in-app agent to this process when the agent reads the network log the next time.

Native network capture stays on until the agent stops it for the app. The capture of a different app continues. stop-all-simulator-servers also stops it for all apps of the device. After the capture stops, restart the app to remove the in-app agent from the app.

Each request has an ID such as android-3f9a-12. The agent uses this ID to read headers and request or response bodies. An ID is valid only in the tool-server that listed it. An ID is not valid after the capture stops for the app or after the tool-server stops.

Only the in-app agent that Argent attached can report requests to Argent.

If native network capture is unavailable, use the JS runtime layer for the requests of the JavaScript code.

The request record​

First the agent reads the list of records in the network log. The content of the list depends on the layer:

LayerList
JS runtime, Chrome DevTools ProtocolOne line for each record
Native NSURLProtocolOne entry for each event, with headers and times
Native OkHttp (native network capture)A header line, then one entry for each request

In the JS runtime layer and in the Chrome DevTools Protocol layer, a line has this format:

{id: rn-net-4} "GET /v1/users" 200 OK Fetch 12.4 kB 143 ms

In the JS runtime layer, the text after the status is the standard reason phrase of the status code, for example OK or Not Found. A request that a redirect sent to a different URL ends with that URL, for example → /v2/users.

A size with ~, for example ~1.2 MB, is approximate. The JS runtime layer shows this size when the size in bytes of a body is not known: for a large text body, or for a binary body that the app reads as text. This size is the length of the body in characters. The size in bytes is equal to this length or larger.

In native network capture, the header line tells if the capture is active, waits for the app to load OkHttp, or is unavailable. For an unavailable capture, the header line gives the reason. Sometimes an active capture gets only some requests of the app. Then the header line tells which requests Argent captures.

Then the agent reads the details of one record by its ID. The native NSURLProtocol layer has no details, because each entry of its list is complete. In the other layers, the details contain these items:

  • The URL, the method and the status. In the JS runtime layer and in native network capture, the details also give the final URL after a redirect.
  • The headers of the request and of the response. In native network capture, the request headers are the headers sent on the wire. They include headers that the app code did not set, for example Cookie and User-Agent. The response headers are the headers that the app received. After OkHttp decodes a gzip response, these headers do not contain Content-Encoding and Content-Length.
  • In native network capture, each redirect before the final response
  • The duration and the size
  • The bodies of the request and of the response
  • For Chromium, the initiator of the request

For the JS runtime layer, native network capture and the Chrome DevTools Protocol layer, Argent replaces the values of secret headers with [REDACTED]. A header is secret if its name contains authorization, cookie, token, api-key or a related word. The native NSURLProtocol layer does not replace these values. See the Limits section.

Argent also shortens a body that is longer than 1000 characters. A message before the shortened body gives the size of the full body. The JS runtime layer can keep only the start of a large body. For such a body, the message gives the full size in bytes, the full length in characters or a minimum length. Native network capture can also keep only the start of a large body. For such a body, the message gives the full size in bytes if Argent knows it, and the number of bytes that the in-app agent kept.

Argent removes the bundle traffic and the HMR traffic of Metro from the network log. Thus the network log contains the requests of your app only. This removal applies only when the app connects to Metro on a local address. If a physical Android device connects to Metro on a network address, for example 192.168.1.20:8081, the network log also contains the requests to Metro.

Example instructions​

  • "The list screen is empty. Examine the response of the API."
  • "Compare the payload of the request before and after my change."
  • "Show the requests that this screen sends at mount. Show their durations."
  • "Make sure that the app sends the second request after the error 500."
  • "Show the requests from the analytics SDK in my Android app."

Limits​

  • Argent does not capture the requests that the app sends before the capture starts. Do the operation again after the capture starts. Argent starts the capture at these moments:
    • JS runtime layer: the agent reads the network log for the first time.
    • Chrome DevTools Protocol layer: Argent attaches to the Chromium app.
    • Native NSURLProtocol layer: the agent reads the network log of this layer for the first time. On a Mac app, the native capture stays on when the app restarts after the first read. On a Mac app, the native capture stops when the tool-server disconnects from the app. The next read of the network log starts the capture again.
    • Native network capture: the in-app agent connects to Argent. This occurs a short time after Argent attaches the in-app agent to a process of the app.
  • A reload or a restart of the app clears the network log of the JS runtime layer. Argent starts the capture again when the agent reads the network log.
  • After an upgrade of Argent, the network capture of the earlier version stays in the app until the app reloads. The earlier network capture keeps no records, but it still reads a copy of each fetch() response. Reload the app to remove the earlier network capture.
  • Expo fetch() does not always report a connection that breaks in the middle of the response body. The app then gets a part of the body, or its read of the body does not end. The record shows the same: that part of the body, or a pending request. If the app does not read the body, the record shows a finished request.
  • If the app aborts an XMLHttpRequest while the response body streams, the record shows a failed request with the error aborted. The record contains the part of the text body that the app received before the abort. For example, react-native-sse aborts its request to close the connection. The same applies to a library request that streams text, for example a react-native-fetch-api request with textStreaming. If the app aborts an Expo fetch() while it streams the body, the record has no body.
  • A fetch() call that fails before it sends the request has no record. An example is a call with a signal that is already aborted.
  • If the app aborts a library request before the network module of React Native gives the request its ID, the request still runs. The app gets an abort error, but the record shows the finished request and its response.
  • If the app does not read the body of a successful Expo fetch() response, the record has no body and no size. A response that cannot have a body, for example the response to a HEAD request, has the size 0.
  • Argent finds the network module of React Native in the list of modules that Metro adds to a development build. Without this list, Argent does not record the requests that a library sends to the network module itself.
  • The network log keeps the most recent records only:
    • The JS runtime layer keeps 2000 records.
    • Native network capture keeps 2000 records. It keeps fewer records when the requests have very large headers or URLs.
    • The Chrome DevTools Protocol layer keeps 1000 records.
    • The native NSURLProtocol layer keeps 1000 protocol events for each app. A request produces several events, so this layer keeps fewer than 1000 requests.
  • The JS runtime layer does not read a binary response body, for example an image, a font, a PDF file or an application/octet-stream body. The record gives the type and the size of the body only. For Chromium, Argent does not show a response body that is not UTF-8 text. The details give the type and the size of this body only.
  • The JS runtime layer keeps approximately the first 1 MB of each body. The JS runtime layer also removes the oldest records when their bodies contain more than 50 MB of text.
  • For Chromium, Argent reads the active tab. If you change the tab, Argent attaches to the new tab. If the page changed after the request, the body of the response can be unavailable.
  • The NSURLProtocol layer records the requests of URLSession sessions with the default configuration or the ephemeral configuration, and of URLSession.shared. The layer does not record these requests:
    • The transfers of a background URLSession. The system does not use a custom NSURLProtocol for background sessions.
    • The connections of Network.framework, for example nw_connection.
    • The requests of a WKWebView, also the fetch() calls in the web page.
    • The requests of an HTTP client that does not use URLSession, for example the HttpClient of Flutter (dart:io).
  • An empty native network log does not prove that the app sent no requests. The app can send requests that the NSURLProtocol layer does not record.
  • On Android 9 or later, native network capture records each OkHttp request that the app starts after Argent attaches the in-app agent. Native network capture does not record these requests:
    • A request that is already running when Argent attaches the in-app agent.
    • The requests of an OkHttp copy in a different class loader, for example a separate plugin loader.
    • In OkHttp 3, the requests of a custom subclass of OkHttpClient.
    • The requests of an HTTP client that does not use OkHttp, for example HttpURLConnection or Cronet. A native module can use such a client.
  • On Android 8.0 and 8.1, native network capture records only a part of the requests. The header line gives the reason. Earlier Android versions do not have native network capture.
    • In a React Native app, it records only the requests of the React Native networking client and of Fresco. It does not record fetch() of Expo, WebSockets, or the OkHttp clients of native modules.
    • In an app without React Native, it records no requests.
  • If R8 fully minifies the OkHttp code of the app, native network capture is unavailable. The header line gives the reason. The requests of the app continue to work.
  • When native network capture records only a part of the requests of the app, the header line says so after capture active:.
  • For WebSockets, native network capture records only the connection request.
  • Native network capture attaches the in-app agent to the main process of the app only. It does not record the requests of a component that runs in its own process, for example a service with android:process=":remote". If the <application> element sets android:process, Argent does not find the app and reads it as not running.
  • Native network capture reads each body from the app process that sent the request. A relaunch or an emulator snapshot load ends that process. After that, a request body or a response body is available only if the agent read it before. Argent keeps a copy of only the 64 most recent bodies that the agent read.
  • If a physical Android device loses its USB connection, the device removes each adb reverse. Argent tries to set the adb reverse of the capture again for approximately 15 seconds. After this time, Argent sets it again at the next native-network-logs call or app launch. Until then, the in-app agent cannot connect.
  • While the in-app agent has no connection, it keeps the events of the requests for a maximum of 60 seconds. After 60 seconds, it turns off the capture and deletes these events. The list then does not contain these requests, and the header line does not say that they are missing. The capture starts again when the in-app agent connects.
  • Native network capture can slow the app. The launch results, the e2e test reports and the profiler start results tell the agent when native network capture is on. Before you profile, ask the agent to stop native network capture for the app. Then restart the app.
  • When Argent stops native network capture, with stop: true or with stop-all-simulator-servers, Argent turns off the capture in the app. Argent also removes the session file and the files of the in-app agent from the app, and removes the adb reverse of the capture. The copies of these files in /data/local/tmp/.argent-inspector stay on the device. A crash or a kill -9 of the tool-server skips these steps. A new tool-server starts the capture again. After a crash or a kill -9, these items stay on the device:
    • The in-app agent stays in the app process until the process ends. The in-app agent tries to connect again every few seconds until then. After 60 seconds, it turns off the capture in the app, but it continues to try to connect. Thus a new tool-server gets the capture of this process back without a restart of the app.
    • The session file and the files of the in-app agent stay in the app until the capture starts and stops again, or until you install the app again.
    • The adb reverse stays until you remove it with adb reverse --remove, until the adb server or the device restarts, or until the USB connection of the device stops. A restart of the adb server also removes the other reverses, for example the reverse of Metro. Each adb reverse that stays holds one device port from 20000 to 29999.
  • Argent does not replace the data in the bodies of the requests and of the responses. Protect a network log as you protect other data of the app.
  • On the native NSURLProtocol layer, Argent does not replace the values of secret headers. The agent sees headers such as Authorization and Cookie in full. Protect a network log of this layer as you protect other data of the app.

Argent does this with these three tools: view-network-logs, view-network-request-details and native-network-logs. The tools reference contains all tools.