SHUYILINK COLLECTOR JS

shuyilink-collector-js Client-side JavaScript log, exception and tracing library.

• Provide metrics and error collection to backend.
• Lightweight
• Make browser as a start of whole distributed tracing
• Base on skywalking-client-js

Usage

Install

The shuyilink-collector-js runtime library is available at npm.

npm install shuyilink-collector-js --save

Quick Start

User could use register method to load and report data automatically.

import ClientCollector from 'shuyilink-collector-js';

Collector.register({
   service: 'ipc-web',
   pagePath: window.location.ref,
   serviceVersion: 'v1.0.0',
   enableLogs: true,
   consoleLogLevels: ['Info', 'Warning', 'Error'],
   useUploadLogs: true
})

Parameters

The register method supports the following parameters.

|Parameter|Type| Description |Required| Default Value | |----|----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----|---------------| |collector|String| In default, the collected data would be reported to current domain(/browser/perfData. Then, typically, we recommend you use a Gateway/proxy to redirect the data to the OAP(resthost:restport). If you set this, the data could be reported to another domain, NOTE the Cross-Origin Resource Sharing (CORS) issuse and solution. |false| - | |service|String| project ID. |true| - | |serviceVersion|String| project verison |true| - | |pagePath|String| project path |true| - | |jsErrors|Boolean| Support js errors monitoring |false| false | |apiErrors|Boolean| Support API errors monitoring |false| false | |resourceErrors|Boolean| Support resource errors monitoring |false| false | |useFmp|Boolean| Collect FMP (first meaningful paint) data of the first screen |false| false | |enableSPA|Boolean| Monitor the page hashchange event and report PV, which is suitable for single page application scenarios |false| true | |autoTracePerf|Boolean| Support sending of performance data automatically. |false| false | |vue|Vue| Support vue errors monitoring |false| undefined | |traceSDKInternal|Boolean| Support tracing SDK internal RPC. |false| false | |detailMode|Boolean| Support tracing http method and url as tags in spans. |false| true | |noTraceOrigins|(string | RegExp)[] |Origin in the noTraceOrigins list will not be traced.| false |[]| |traceTimeInterval|Number| Support setting time interval to report segments. |false| 60000 | |customTags|Array| Custom Tags |false| - | |enableTraceSegment|Boolean| 是否开启链路追踪 |false| false | |enableLogs|Boolean| 是否开启手动日志采集 |false| true | |useConsoleLog|Boolean| 是否开启控制台打印日志 |false| true | |consoleLogLevels|Array| 控制台打印的日志等级 |false| - | |useUploadLogs|Boolean| 是否开启日志上报 |false| false | |logsBufferSize|Number| 日志采集器的容量限制 |false| 10000 | |uploadLogsLevels|Array| 日志上报的等级 |false| - | |uploadLogsTimeInterval|Number| 日志上报的时间间隔 |false| 10000 | |uploadLogsBatchSize|Number| 日志上报的单次条数限制 |false| 10000 | |customUrlForLogs|String| 定制的日志上报接口 |true| - | |customUrlForErrors|String| 定制的错误上报接口（单条） |true| - | |customUrlForError|String| 定制的错误上报接口 |true| - | |customUrlForPerf|String| 定制的性能分析上报接口 |true| - | |customUrlForSegment|String| 定制的链路追踪上报接口（单条） |true| - | |customUrlForSegments|String| 定制的链路追踪上报接口 |true| - |

Collect Metrics Manually

Use the setPerformance method to report metrics at the moment of page loaded or any other moment meaningful.

1. Set the SDK configuration item autoTracePerf to false to turn off automatic reporting performance metrics and wait for manual triggering of escalation.
2. Call Collector.setPerformance(object) method to report

• Examples

import Collector from 'shuyilink-collector-js';

Collector.setPerformance({
  collector: 'http://127.0.0.1:12800',
  service: 'browser-app',
  serviceVersion: '1.0.0',
  pagePath: location.href,
  useFmp: true
});

Special scene

SPA Page

In spa (single page application) single page application, the page will be refreshed only once. The traditional method only reports PV once after the page loading, but cannot count the PV of each sub-page, and can't make other types of logs aggregate by sub-page.
The SDK provides two processing methods for spa pages:

1. Enable spa automatic parsing
   This method is suitable for most single page application scenarios with URL hash as the route.
   In the initialized configuration item, set enableSPA to true, which will turn on the page's hashchange event listening (trigger re reporting PV), and use URL hash as the page field in other data reporting.
2. Manual reporting
   This method can be used in all single page application scenarios. This method can be used if the first method is invalid.
   The SDK provides a set page method to manually update the page name when data is reported. When this method is called, the page PV will be re reported by default. For details, see setPerformance().

app.on('routeChange', function (next) {
   Collector.setPerformance({
      collector: 'http://127.0.0.1:12800',
      service: 'browser-app',
      serviceVersion: '1.0.0',
      pagePath: location.href,
      useFmp: true
   });
});   

Collect logs manually

It's similar to console.log / console.warn / console.error

Collector.info(`TestLogCollector >> ${count} >> Info`, 'xxxx')

Collector.warn(`TestLogCollector >> ${count} >> Warning`, 'xxxx')

Collector.error(`TestLogCollector >> ${count} >> Error`, 'xxxx')

Tracing range of data requests in the browser

Support tracking these(XMLHttpRequest and Fetch API) two modes of data requests. At the same time, Support tracking libraries and tools that base on XMLHttpRequest and fetch, such as Axios, SuperAgent, OpenApi and so on.

Catching errors in frames

// Vue
Vue.config.errorHandler = (error) => {
   Collector.reportFrameErrors({
      collector: 'http://127.0.0.1:12800',
      service: 'vue-demo',
      pagePath: '/app',
      serviceVersion: 'v1.0.0',
   }, error);
}

According to different pages or modules, add custom tags to spans.

app.on('routeChange', function () {
   Collector.setCustomTags([
      {key: 'key1', value: 'value1'},
      {key: 'key2', value: 'value2'},
   ]);
});

License

Apache 2.0