commit | 786bba4b2e1416ceb43c30f90706fe910f5c5461 | [log] [tgz] |
---|---|---|
author | Fine0830 <fanxue0830@gmail.com> | Mon Oct 10 20:59:30 2022 +0800 |
committer | GitHub <noreply@github.com> | Mon Oct 10 20:59:30 2022 +0800 |
tree | 9506c1b5b377a3fcc487bad0e8c82b996684534e | |
parent | 7be3caf89b7023fd6884d0a81e27747d4ec0105f [diff] |
docs: update changes and version (#103)
Apache SkyWalking Client-side JavaScript exception and tracing library.
NOTICE, SkyWalking Client JS 0.8.0 and later versions require SkyWalking v9.
The skywalking-client-js
runtime library is available at npm.
npm install skywalking-client-js --save
skywalking-client-js
requires SkyWalking 8.2+
User could use register
method to load and report data automatically.
import ClientMonitor from 'skywalking-client-js';
// Report collected data to `http:// + window.location.host + /browser/perfData` in default ClientMonitor.register({ # Use core/default/restPort in the OAP server. # If External Communication Channels are activated, `receiver-sharing-server/default/restPort`, # ref to https://skywalking.apache.org/docs/main/latest/en/setup/backend/backend-expose/ collector: 'http://127.0.0.1:12800', service: 'test-ui', pagePath: '/current/page/name', serviceVersion: 'v1.0.0', });
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 | true |
apiErrors | Boolean | Support API errors monitoring | false | true |
resourceErrors | Boolean | Support resource errors monitoring | false | true |
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 | false |
autoTracePerf | Boolean | Support sending of performance data automatically. | false | true |
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 | - |
Use the setPerformance
method to report metrics at the moment of page loaded or any other moment meaningful.
ClientMonitor.setPerformance(object)
method to reportimport ClientMonitor from 'skywalking-client-js'; ClientMonitor.setPerformance({ collector: 'http://127.0.0.1:12800', service: 'browser-app', serviceVersion: '1.0.0', pagePath: location.href, useFmp: true });
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:
app.on('routeChange', function (next) { ClientMonitor.setPerformance({ collector: 'http://127.0.0.1:12800', service: 'browser-app', serviceVersion: '1.0.0', pagePath: location.href, useFmp: true }); });
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.
// Angular import { ErrorHandler } from '@angular/core'; import ClientMonitor from 'skywalking-client-js'; export class AppGlobalErrorhandler implements ErrorHandler { handleError(error) { ClientMonitor.reportFrameErrors({ collector: 'http://127.0.0.1:12800', service: 'angular-demo', pagePath: '/app', serviceVersion: 'v1.0.0', }, error); } } @NgModule({ ... providers: [{provide: ErrorHandler, useClass: AppGlobalErrorhandler}] }) class AppModule {}
// React class ErrorBoundary extends React.Component { constructor(props) { super(props); this.state = { hasError: false }; } static getDerivedStateFromError(error) { // Update state so the next render will show the fallback UI. return { hasError: true }; } componentDidCatch(error, errorInfo) { // You can also log the error to an error reporting service ClientMonitor.reportFrameErrors({ collector: 'http://127.0.0.1:12800', service: 'react-demo', pagePath: '/app', serviceVersion: 'v1.0.0', }, error); } render() { if (this.state.hasError) { // You can render any custom fallback UI return <h1>Something went wrong.</h1>; } return this.props.children; } } <ErrorBoundary> <MyWidget /> </ErrorBoundary>
// Vue Vue.config.errorHandler = (error) => { ClientMonitor.reportFrameErrors({ collector: 'http://127.0.0.1:12800', service: 'vue-demo', pagePath: '/app', serviceVersion: 'v1.0.0', }, error); }
app.on('routeChange', function () { ClientMonitor.setCustomTags([ { key: 'key1', value: 'value1' }, { key: 'key2', value: 'value2' }, ]); });
The SkyWalking client-js agent would be deployed and running outside of your datacenter. This means when you introduce this component you should be aware of the security impliciations. There are various kinds of telemetry relative data would be reported to backend separately or through your original HTTP requests.
In order to implement distributed tracing from the browser, an HTTP header with the name sw8
will be added to HTTP requests according to Cross Process Propagation Headers Protocol v3. client-js
will also report spans and browser telemetry data through Trace Data Protocol v3 and Browser Protocol.
Because all of this data is reported from an unsecured environment, users should make sure to:
Please consult your security team before introducing this feature in your production environment. Don‘t expose the OAP server’s IP/port(s) and URI without a security audit.
Demo project provides instrumented web application with necessary environment, you could just simple use it to see the data SkyWalking collected and how SkyWalking visualizes on the UI. See more information, click here.
dev-subscribe@skywalking.apache.org
, follow the reply to subscribe the mail list.#skywalking
channel at Apache Slack. If the linke is not working, find the latest one at Apache INFRA WIKI.All committers should follow Release Guide to publish the official release.
Apache 2.0