diff --git a/docs/recipes/network.md b/docs/recipes/network.md new file mode 100644 index 0000000000..1d4f165b21 --- /dev/null +++ b/docs/recipes/network.md @@ -0,0 +1,97 @@ +# network recorder and replayer + +Starting from v2.0.0, we add the plugin to record network output. +This feature aims to provide developers with more information about the bug scene. There are some options for recording and replaying network output. + +### Enable recording network + +You can enable using default option like this: + +```js +rrweb.record({ + emit: function emit(event) { + events.push(event); + }, + // to use default record option + plugins: [rrweb.getRecordNetworkPlugin()], +}); +``` + +You can also customize the behavior of logger like this: + +```js +rrweb.record({ + emit: function emit(event) { + fetch('https://api.my-server.com/events', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + events: [event], + }), + }); + }, + // customized record options + plugins: [ + rrweb.getRecordConsolePlugin({ + initiatorTypes: ['fetch', 'xmlhttprequest'], + // block recording event for request to upload events to server + ignoreRequestFn: ({ performanceEntry }) => { + if (performanceEntry.name === 'https://api.my-server.com/events') { + return true; + } + return false; + }, + recordHeaders: true, + recordBody: true, + recordInitialRequests: false, + }), + ], +}); +``` + +**alert**: If you are uploading events to a server, you should always use `ignoreRequestFn` to block recording events for these requests or else you will cause a nasty loop. + +All options are described below: +| key | default | description | +| ---------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| initiatorTypes | `['fetch','xmlhttprequest','img',...]` | Default value contains names of all [initiator types](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/initiatorType). You can override it by setting the types you need. | +| ignoreRequestFn | `() => false` | Block recording events for specific requests | +| recordHeaders | `false` | Record the request & response headers for `fetch` and `xmlhttprequest` requests | +| recordBody | `false` | Record the request & response bodies for `fetch` and `xmlhttprequest` requests | +| recordInitialRequests | `false` | Record an event for all requests prior to rrweb.record() being called | + +## replay network + +It is up to you to decide how to best replay your network events using the `onNetworkData` callback. + +```js +const replayer = new rrweb.Replayer(events, { + plugins: [ + rrweb.getReplayNetworkPlugin({ + onNetworkData: ({ requests }) => { + for (const request of requests) { + const url = request.performanceEntry.name; + const method = request.responseMethod; + const status = request.responseStatus; + console.log(`${method} ${url} ${status}`); + } + }, + }), + ], +}); +replayer.play(); +``` + +Description of replay option is as follows: + +| key | default | description | +| ------------- | ----------- | ------------------------------------------------------------------------------------------ | +| onNetworkData | `undefined` | You could use this interface to replay the network requests in a simulated browser console | + +## technical implementation + +This implementation records [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) by patching their object & methods. We record document navigation using [`PerformanceNavigationTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming) and we use [`PerformanceResourceTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming) for recording everything else (script, img, link etc.) via [`PerformanceObserver`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver) API. + +For more information please see [[network-plugin] Feat: Capture network events #1105](https://github.com/rrweb-io/rrweb/pull/1105) PR.