web-client-js
Version:
Client-side JavaScript exception and tracing library
112 lines (86 loc) • 10.8 kB
Markdown
# Web Client JS
[Web Client Js](https://www.npmjs.com/package/web-client-js) 客户端 JavaScript 异常和跟踪库，并向 Web 后端提供指标和错误收集。
## 安装
```
npm install web-client-js --save
```
## 步骤一：接入SDK
```js
import browserClient from 'web-client-js';
```
```js
// 默认上报收集的数据到 `http:// + window.location.host + /browser/perfData`
browserClient('init', {
collector: 'http://127.0.0.1:12800',
service: 'APM-FRONTEND-APM',
serviceVersion: 'V1.1.0',
pagePath: location.href,
useFmp: true
})
browserClient('start')
```
## （可选）步骤二：详细配置
在上述示例中只配置了基础参数，还有多个配置项。所有支持的配置项字段名和字段意义如下：
| 参数 | 类型 | 描述 | 必填 | 默认值 |
| ----------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- |
| collector | String | 默认情况下，收集的数据将被上报到当前域名(`/browser/perfData`)； 不过， 通常我们推荐你使用网关/代理重定向这些数据到OAP(`resthost:restport`)。如果你设置了这一项, 这些数据会被上报到你设置的域名。 注意跨域问题： [跨源资源共享解决方案](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS). | false | - |
| service | String | 项目标识名称 | true | - |
| serviceVersion | String | 项目版本号 | true | - |
| pagePath | String | 项目路径，显示在后台的数据来源路径 | true | - |
| jsErrors | Boolean | 支持 js 异常监控 | false | true |
| apiErrors | Boolean | 支持 API 异常监控 | false | true |
| resourceErrors | Boolean | 支持资源异常监控 | false | true |
| useFmp | Boolean | 收集第一屏 FMP (first meaningful paint) 数据 | false | false |
| enableSPA | Boolean | 监控页面 hashchange 事件然后上报 PV, 适用于单页应用场景 | false | false |
| autoTracePerf | Boolean | 支持自动发送性能数据 | false | true |
| vue | Vue | 支持 vue 错误监控 | false | undefined |
| traceSDKInternal | Boolean | 支持跟踪 SDK 内部 RPC | false | false |
| detailMode | Boolean | 支持在跨度中将 http 方法和 url 作为标签进行跟踪. | false | true |
| noTraceOrigins | (string \| RegExp)[] | `noTraceOrigins` 列表中的源将不会被跟踪 | false | [] |
| traceTimeInterval | Number | 支持设置上报segments的间隔时间 | false | 60000 |
## 步骤三：验证上报
## 特殊场景
### SPA 页面
在 spa (single page application) 单页应用中, 页面只会刷新一次. 传统方法只能在页面加载完以后上报一次PV, 不能计算每一个子页的PV,更不能在子页做其他的日志记录。
此SDK为单页应用提供2种方法上报:
1. 启用 spa 自动解析
该方法适用于大多数以URL哈希为路由的单页应用场景。
在初始设置项中, 设置 enableSPA 为 true,将会开启页面 hashchange 事件监听 (触发重新上报 PV), 并在其他数据报告中使用网址哈希作为页面字段。
2. 手动上报
这个方法可以用在所有单页应用场景。当第一种方法失效时可以使用此方法。
此SDK提供一个设置页面方法来使上报时更新页面名称，当方法被调用，页面PV将被重新上报。
```js
app.on('routeChange', function (next) {
browserClient('init', {
collector: 'http://127.0.0.1:12800',
service: 'browser-app',
serviceVersion: '1.0.0',
pagePath: location.href,
useFmp: true,
})
browserClient('start')
});
```
### 客户端网关服务器配置
```config
server {
keepalive_requests 120; #单连接请求上限次数。
listen 8081; #监听端口
server_name 127.0.0.1; #监听地址
location / { #请求的url过滤，正则匹配，~为区分大小写，~*为不区分大小写。
root /Users/chenfei/study/vue01/dist/; # 这个路径是存放打包后的 前端项目dist的路径
index index.html; # 访问入口文件
}
# 切记， 在docker启动的nginx 必须将该文件中所有的 localhost 改成服务器的 内网ip （不能为 127.0.0.1）
location /browser {
proxy_set_header Host $host:$server_port;
proxy_redirect off;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_connect_timeout 60;
proxy_read_timeout 600;
proxy_send_timeout 600;
proxy_pass http://127.0.0.1:12800/browser;
}
}
```