docs: add document for console recording and playback (rrweb-io#435)

* docs: add document for console recording and playback * docs: adjust some sentences
livecycle · Dec 8, 2020 · 4b589b3 · 4b589b3
1 parent 4e7146e
commit 4b589b3
Show file tree

Hide file tree

Showing 6 changed files with 151 additions and 0 deletions.
diff --git a/docs/recipes/console.md b/docs/recipes/console.md
@@ -0,0 +1,68 @@
+# console recorder and replayer
+
+Starting with a later version of v0.9.11, we add the ability to record and play back console output. 
+This feature aims to provide developers with more information about the bug scene. There are some options for recording and replaying console output.
+
+### Enable recording console
+You can enable the logger using default option like this:
+```js
+rrweb.record({
+  emit: emit(event) {
+    // you should use console.log in this way to avoid errors.
+    const defaultLog = console.log["__rrweb_original__"]?console.log["__rrweb_original__"]:console.log;
+    defaultLog(event);
+  },
+  // to use default record option
+  recordLog: true,
+});
+```
+
+**alert**: You shouldn't call console.log(warn, error .etc) in the emit function or you would get the error: `Uncaught RangeError: Maximum call stack size exceeded`.
+You should call console.log.\_\_rrweb_original__() instead.
+
+You can also customize the behavior of logger like this:
+```js
+rrweb.record({
+  emit: emit(event) {
+    // you should use console.log in this way to avoid errors.
+    const defaultLog = console.log["__rrweb_original__"]?console.log["__rrweb_original__"]:console.log;
+    defaultLog(event);
+  },
+  // customized options
+  recordLog: {
+    level: ["info", "log", "warn", "error"],
+    lengthThreshold: 10000,
+    stringifyOptions: {
+      stringLengthLimit: 1000,
+      numOfKeysLimit: 100,
+    },
+    logger: window.console,
+  },
+});
+```
+All recordLog options are described below:
+| key              | default                                                           | description                                                                                                                                                                                                                                                                                                                             |
+| ---------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| level            | ['log','warn','error',...]                                        | Default value contains names of all console functions. You can override it by setting console levels you need.                                                                                                                                                                                                                          |
+| lengthThreshold  | 1000                                                              | Maximum number of records of console output.                                                                                                                                                                                                                                                                                            |
+| stringifyOptions | {        stringLengthLimit: undefined,       numOfKeysLimit: 50 } | If console output includes js objects, we need to stringify them. `stringLengthLimit` limits the string length of single value. `numOfKeysLimit` limits the number of keys in an object. If an object contains more keys than this limit, we would only save object's name. You can reduce the size of events by setting these options. |
+| logger           | window.console                                                    | the console object we would record.You can set a console object from another execution environment where you would like to record.                                                                                                                                                                                                      |
+
+## replay console
+If recorded events include data of console log type, we will automatically play them.
+
+```js
+const replayer = new rrweb.Replayer(events, {
+  logConfig: {
+    level: ["info", "log", "warn", "error"]
+  },
+});
+replayer.play();
+```
+
+Description of replay option is as follows:
+
+| key          | default                                                                                      | description                                                                                                                             |
+| ------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| level        | ['log','warn','error',...]                                                                   | Same meaning as that option in recordLog. You can set this option to play levels of log you need.                                       |
+| replayLogger | a console based object that implements the interface [ReplayLogger](../../src/types.ts#L417) | You can also set a replay logger to replay the log messages in a simulated browser console by implementing the interface `ReplayLogger` |
diff --git a/docs/recipes/console.zh_CN.md b/docs/recipes/console.zh_CN.md
@@ -0,0 +1,66 @@
+# console 录制和播放
+
+从v0.9.11的下一个版本开始，我们增加了录制和播放控制台输出的功能。这个功能旨在为开发者提供更多的bug信息。对这项功能我们还提供了一些设置选项。
+
+### 开启录制console功能
+可以通过如下代码使用默认的配置选项
+```js
+rrweb.record({
+  emit: emit(event) {
+    // 如果要使用console来输出信息，请使用如下的写法
+    const defaultLog = console.log["__rrweb_original__"]?console.log["__rrweb_original__"]:console.log;
+    defaultLog(event);
+  },
+  // 使用默认的配置选项
+  recordLog: true,
+});
+```
+
+**警告**: 在emit函数中你不应该直接调用console.log等函数，否则将会得到报错：`Uncaught RangeError: Maximum call stack size exceeded`。
+你应该调用console.log.\_\_rrweb_original__()来避免错误。
+
+你也可以定制录制console的选项
+```js
+rrweb.record({
+  emit: emit(event) {
+    // 如果要使用console来输出信息，请使用如下的写法
+    const defaultLog = console.log["__rrweb_original__"]?console.log["__rrweb_original__"]:console.log;
+    defaultLog(event);
+  },
+  // 定制的选项
+  recordLog: {
+    level: ["info", "log", "warn", "error"],
+    lengthThreshold: 10000,
+    stringifyOptions: {
+      stringLengthLimit: 1000,
+      numOfKeysLimit: 100,
+    },
+    logger: window.console,
+  },
+});
+```
+如下是配置选项的详细说明：
+| key              | 默认值                                                            | 功能                                                                                                                                                                                                                                                                               |
+| ---------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| level            | ['log','warn','error',...]                                        | 默认值包含了console的全部函数，你也可以传入想要录制的console函数。                                                                                                                                                                                                                 |
+| lengthThreshold  | 1000                                                              | 录制console输出信息的最大条数。                                                                                                                                                                                                                                                    |
+| stringifyOptions | {        stringLengthLimit: undefined,       numOfKeysLimit: 50 } | 如果console输出包含了js对象，我们需要对其进行序列化，`stringLengthLimit` 限制了单个值能转化的最大字符串长度，`numOfKeysLimit` 限制了一个被序列化的js对象能够包含的最大数量key，如果对象的key数量超过了这个限制，我们将只保留对象的名字。你能通过这些选项来减小生成的events的体积。 |
+| logger           | window.console                                                    | 要录制的console对象，你也可以传入一个想要录制的其他js执行环境的console对象。                                                                                                                                                                                                       |
+
+## 播放console数据
+如果replayer传入的events中包含了console类型的数据，我们将自动播放这些数据。
+
+```js
+const replayer = new rrweb.Replayer(events, {
+  logConfig: {
+    level: ["info", "log", "warn", "error"]
+  },
+});
+replayer.play();
+```
+如下是对replay选项的描述：
+
+| key          | 默认值                                                               | 功能                                                                                                    |
+| ------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| level        | ['log','warn','error',...]                                           | 与recordLog设置选项的含义相同，你可以只播放想要的console函数类型                                        |
+| replayLogger | 一个基于console的对接口[ReplayLogger](../../src/types.ts#L417)的实现 | 你也可以通过传入一个`ReplayLogger`接口的自己的实现，用html模拟一个浏览器控制台，来播放录制的console数据 |
diff --git a/docs/recipes/index.md b/docs/recipes/index.md
@@ -65,3 +65,10 @@ In some Apps, rrweb may record an unexpected amount of data. This part will help
 Canvas is a special HTML element, which will not be recorded by rrweb by default. There are some options for recording and replaying Canvas.
 
 [link](./canvas.md)
+
+### Console Recorder and Replayer
+
+Starting with a later version of v0.9.11, we add the ability to record and play back console output. 
+This feature aims to provide developers with more information about the bug scene. There are some options for recording and replaying console output.
+
+[link](./console.md)
diff --git a/docs/recipes/index.zh_CN.md b/docs/recipes/index.zh_CN.md
@@ -63,3 +63,9 @@ rrweb 录制的数据是一种高效、易于压缩的文本格式，可以用
 Canvas 是一种特殊的 HTML 元素，默认情况下其内容不会被 rrweb 观测。我们可以通过特定的配置让 rrweb 能够录制并回放 Canvas。
 
 [链接](./canvas.zh_CN.md)
+
+### console录制和播放
+
+从v0.9.11的下一个版本开始，我们增加了录制和播放控制台输出的功能。这个功能旨在为开发者提供更多的bug信息。对这项功能我们还提供了一些设置选项。
+
+[链接](./console.zh_CN.md)
diff --git a/guide.md b/guide.md
@@ -150,6 +150,7 @@ The parameter of `rrweb.record` accepts the following options.
 | sampling         | -           | refer to the [storage optimization recipe](./docs/recipes/optimize-storage.md)                                                                                   |
 | recordCanvas     | false       | whether to record the canvas element                                                                                                                             |
 | collectFonts     | false       | whether to collect fonts in the website                                                                                                                          |
+| recordLog        | false       | whether to record console output, refer to the [console recipe](./docs/recipes/console.md)                                                                       |
 
 #### Privacy
 
@@ -291,6 +292,7 @@ The replayer accepts options as its constructor's second parameter, and it has t
 | UNSAFE_replayCanvas | false         | whether to replay the canvas element. **Enable this will remove the sandbox, which is unsafe.**                                                                                                                                |
 | mouseTail           | true          | whether to show mouse tail during replay. Set to false to disable mouse tail. A complete config can be found in this [type](https://github.com/rrweb-io/rrweb/blob/9488deb6d54a5f04350c063d942da5e96ab74075/src/types.ts#L407) |
 | unpackFn            | -             | refer to the [storage optimization recipe](./docs/recipes/optimize-storage.md)                                                                                                                                                 |
+| logConfig           | -             | configuration of console output playback, refer to the [console recipe](./docs/recipes/console.md)                                                                                                                             |
 
 #### Use rrweb-player
 

diff --git a/guide.zh_CN.md b/guide.zh_CN.md
@@ -146,6 +146,7 @@ setInterval(save, 10 * 1000);
 | sampling         | -           | 数据抽样策略，详见[优化存储策略](./docs/recipes/optimize-storage.zh_CN.md)                                                                                         |
 | recordCanvas     | false       | 是否记录 canvas 内容                                                                                                                                               |
 | collectFonts     | false       | 是否记录页面中的字体文件                                                                                                                                           |
+| recordLog        | false       | 是否记录console 输出，详见[console录制和播放](./docs/recipes/console.zh_CN.md)                                                                                     |
 
 #### 隐私
 
@@ -287,6 +288,7 @@ replayer.pause(5000);
 | UNSAFE_replayCanvas | false         | 回放时是否回放 canvas 内容，**开启后将会关闭沙盒策略，导致一定风险**                                                                                                                                 |
 | mouseTail           | true          | 是否在回放时增加鼠标轨迹。传入 false 可关闭，传入对象可以定制轨迹持续时间、样式等，配置详见[类型](https://github.com/rrweb-io/rrweb/blob/9488deb6d54a5f04350c063d942da5e96ab74075/src/types.ts#L407) |
 | unpackFn            | -             | 数据解压缩函数，详见[优化存储策略](./docs/recipes/optimize-storage.zh_CN.md)                                                                                                                         |
+| logConfig           | -             | console logger数据播放设置，详见[console录制和播放](./docs/recipes/console.zh_CN.md)                                                                                                                 |
 
 #### 使用 rrweb-player