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.
Capture layers
Argent captures traffic in four layers.
| Layer | Platforms | Content |
|---|---|---|
| JS runtime | iOS, Android, Vega | The XMLHttpRequest calls, also from axios, and the fetch() calls of React Native and Expo |
Native NSURLProtocol | iOS, Mac apps | The URLSession requests, also from native modules. See the Limits section |
| Native OkHttp | Android | OkHttp requests from a debuggable app |
| Chrome DevTools Protocol | Chromium and Electron | All 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 thefetch()function of React Native useXMLHttpRequest.- The
fetch()function of Expo (expo/fetch), also when the app imports it directly. Expo SDK 56 and later use this function as the globalfetch(). - 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:
| Layer | List |
|---|---|
| JS runtime, Chrome DevTools Protocol | One line for each record |
Native NSURLProtocol | One 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
CookieandUser-Agent. The response headers are the headers that the app received. After OkHttp decodes a gzip response, these headers do not containContent-EncodingandContent-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
NSURLProtocollayer: 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
XMLHttpRequestwhile the response body streams, the record shows a failed request with the erroraborted. The record contains the part of the text body that the app received before the abort. For example,react-native-sseaborts its request to close the connection. The same applies to a library request that streams text, for example a react-native-fetch-api request withtextStreaming. If the app aborts an Expofetch()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 aHEADrequest, 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
NSURLProtocollayer 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-streambody. 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
NSURLProtocollayer records the requests ofURLSessionsessions with the default configuration or the ephemeral configuration, and ofURLSession.shared. The layer does not record these requests:- The transfers of a background
URLSession. The system does not use a customNSURLProtocolfor background sessions. - The connections of
Network.framework, for examplenw_connection. - The requests of a
WKWebView, also thefetch()calls in the web page. - The requests of an HTTP client that does not use
URLSession, for example theHttpClientof Flutter (dart:io).
- The transfers of a background
- An empty native network log does not prove that the app sent no requests. The app can send requests that the
NSURLProtocollayer 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
HttpURLConnectionor 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.
- In a React Native app, it records only the requests of the React Native networking client and of Fresco. It does not record
- 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 setsandroid: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 theadb reverseof the capture again for approximately 15 seconds. After this time, Argent sets it again at the nextnative-network-logscall 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: trueor withstop-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 theadb reverseof the capture. The copies of these files in/data/local/tmp/.argent-inspectorstay on the device. A crash or akill -9of the tool-server skips these steps. A new tool-server starts the capture again. After a crash or akill -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 reversestays until you remove it withadb 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. Eachadb reversethat 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
NSURLProtocollayer, Argent does not replace the values of secret headers. The agent sees headers such asAuthorizationandCookiein 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.