Browser Log Collection¶

Actively send log data of different levels (source:browser_log corresponding to the metric type log data) from a web browser or JavaScript client to Guance.

Custom log data collection, integrated into client applications via SDK, collecting different log data for various scenarios.
Automatically collects error information from the application side (including network errors, console errors, and JavaScript errors) and reports them to Guance.
Custom error levels (debug, critical, error, info, warn), custom Logger objects, and custom Log fields.
Automatically collects RUM related data, associating with RUM business scenarios.

Getting Started¶

Prerequisites¶

DataKit AccessPublic OpenWay

Ensure DataKit is installed and configured to be publicly accessible, and install the IP geolocation library.
When integrating the SDK, set datakitOrigin to the domain name or IP of DataKit.

Obtain parameters such as clientToken and site from the console.
No need to configure datakitOrigin when integrating the SDK; data will be sent to the public DataWay by default.

SDK Configuration¶

Access Method	Introduction
NPM	By bundling the SDK code together with your frontend project, this method ensures no impact on frontend page performance, but may miss requests and errors before SDK initialization.
CDN Async Loading	Introducing the SDK script via CDN accelerated caching as an asynchronous script ensures that downloading the SDK script does not affect page loading performance, but may miss requests and errors before SDK initialization.
CDN Sync Loading	Introducing the SDK script via CDN accelerated caching as a synchronous script ensures collection of all errors, resources, requests, and performance metrics. However, it may affect page loading performance.

NPM¶

import { datafluxLogs } from "@cloudcare/browser-logs"
datafluxLogs.init({
  datakitOrigin: "<DataKit domain or IP>", // Required for DK access method
  clientToken: "clientToken", // Required for public OpenWay access
  site: "Public OpenWay address", // Required for public OpenWay access
  //service: 'browser',
  //forwardErrorsToLogs:true
})

CDN Async Loading¶

<script>
  ;(function (h, o, u, n, d) {
    h = h[d] = h[d] || {
      q: [],
      onReady: function (c) {
        h.q.push(c)
      },
    }
    d = o.createElement(u)
    d.async = 1
    d.src = n
    n = o.getElementsByTagName(u)[0]
    n.parentNode.insertBefore(d, n)
  })(
    window,
    document,
    "script",
    "https://static.guance.com/browser-sdk/v3/dataflux-logs.js",
    "DATAFLUX_LOGS"
  )
  DATAFLUX_LOGS.onReady(function () {
    DATAFLUX_LOGS.init({
      datakitOrigin: "<DataKit domain or IP>", // Required for DK access method
      clientToken: "clientToken", // Required for public OpenWay access
      site: "Public OpenWay address", // Required for public OpenWay access
      //service: 'browser',
      //forwardErrorsToLogs:true
    })
  })
</script>

CDN Sync Loading¶

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-logs.js"
  type="text/javascript"
></script>
<script>
  window.DATAFLUX_LOGS &&
    window.DATAFLUX_LOGS.init({
      datakitOrigin: "<DataKit domain or IP>", // Required for DK access method
      clientToken: "clientToken", // Required for public OpenWay access
      site: "Public OpenWay address", // Required for public OpenWay access
      //service: 'browser',
      //forwardErrorsToLogs:true
    })
</script>

Configuration¶

Initialization Parameters¶

Parameter	Type	Required	Default	Description
`datakitOrigin`	String	Yes		DataKit data reporting Origin Note: `protocol (including ://), domain name (or IP address) [and port number]` e.g., https://www.datakit.com, http://100.20.34.3:8088.
`clientToken`	String	Yes		Token for reporting data via openway, obtained from the Guance console, required (public openway access).
`site`	String	Yes		Address for reporting data via public openway, obtained from the Guance console, required (public openway access).
`service`	String	No	`browser`	Log Service name
`env`	String	No		Current environment of the web application, e.g., Prod: production environment; Gray: grayscale environment; Pre: pre-release environment Common: daily environment; Local: local environment;
`version`	String	No		Version number of the web application
`sessionSampleRate`	Number	No	`100`	Metric data collection percentage: `100` means full collection, `0` means no collection
`tracingSampleRate`	Number	No	`100`	Trace data sampling percentage: `100` means full collection, `0` means no collection
`forwardErrorsToLogs`	Boolean	No	`true`	Set to `false` to stop collecting console.error, js, and network errors reported to Guance log data
`silentMultipleInit`	Boolean	No	`false`	Disallow multiple log objects from being initialized
`forwardConsoleLogs`	String/Array			Browser console log types to collect, optional values: `error`, `log`, `info`, `warn`, `error`
`storeContextsToLocal`	Boolean	No		Version requirement: `>3.1.2`. Whether to cache user-defined data to local localstorage, e.g., custom data added by `setUser`, `addGlobalContext` APIs.
`storeContextsKey`	String	No		Version requirement: `>3.1.18`. Define the key for storage in localstorage, default is empty, auto-generated. This parameter is mainly to distinguish sharing store issues under the same domain name but different subpaths.

Usage¶

After the SDK is initialized in the application, custom configuration of log data can be done through the exposed JS API.

logger.debug | info | warn | error | critical (message: string, messageContext = Context)

NPM¶

import { datafluxLogs } from "@cloudcare/browser-logs"

datafluxLogs.logger.info("Button clicked", { name: "buttonName", id: 123 })

CDN Async¶

DATAFLUX_LOGS.onReady(function () {
  DATAFLUX_LOGS.logger.info("Button clicked", { name: "buttonName", id: 123 })
})

CDN Sync¶

window.DATAFLUX_LOGS && DATAFLUX_LOGS.logger.info("Button clicked", { name: "buttonName", id: 123 })

Return Data Structure¶

{
  "service": "browser",
  "session": {
    "id": "c549c2b8-4955-4f74-b7f8-a5f42fc6e79b"
  },
  "type": "logger",
  "_dd": {
    "sdk_name": "Web LOG SDK",
    "sdk_version": "1.0.0",
    "env": "",
    "version": ""
  },
  "device": {
    "os": "Mac OS",
    "os_version": "10.14.6",
    "os_version_major": "10",
    "browser": "Chrome",
    "browser_version": "90.0.4430.85",
    "browser_version_major": "90",
    "screen_size": "2560*1440",
    "network_type": "3g",
    "divice": "PC"
  },
  "user": {},
  "date": 1621321916756,
  "view": {
    "referrer": "",
    "url": "http://localhost:8080/",
    "host": "localhost:8080",
    "path": "/",
    "path_group": "/",
    "url_query": "{}",
    "id": "5dce64f4-8d6d-411a-af84-c41653ccd94a"
  },
  "application": {
    "id": "app_idxxxxxx"
  },
  "message": "XHR error get http://testing-ft2x-api.cloudcare.cn/api/v1/workspace/xxx",
  "status": "error",
  "tags": {},
  "error": {
    "source": "network",
    "stack": "Failed to load"
  },
  "resource": {
    "method": "get",
    "status": 0,
    "status_group": 0,
    "url": "http://testing-ft2x-api.cloudcare.cn/api/v1/workspace/xxx",
    "url_host": "testing-ft2x-api.cloudcare.cn",
    "url_path": "/api/v1/workspace/xxx",
    "url_path_group": "/api/?/workspace/xxx"
  }
}

Status Parameter¶

After initializing the SDK, you can use the provided log API to define different types of statuses.

log (message: string, messageContext: Context, status? = 'debug' | 'info' | 'warn' | 'error' | 'critical')

NPM¶

import { datafluxLogs } from '@cloudcare/browser-logs'

datafluxLogs.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);

CDN Async¶

DATAFLUX_LOGS.onReady(function () {
  DATAFLUX_LOGS.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);
})

CDN Sync¶

window.DATAFLUX_LOGS && DATAFLUX_LOGS.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);

Parameter Description¶

Parameter	Description
`<MESSAGE>`	The Message field in Guance logs
`<JSON_ATTRIBUTES>`	Additional data describing the Message, a Json object
`<STATUS>`	Log level, optional values `debug`, `info`, `warn`, `error`, `critical`

Custom Adding Extra Data TAGs¶

After initializing LOG, use the setGlobalContextProperty(key:string, value:any) API to add extra TAGs to all LOG events collected from the application.

Add TAG¶

CDN SyncCDN AsyncNPM

window.DATAFLUX_LOGS && window.DATAFLUX_LOGS.setGlobalContextProperty('<CONTEXT_KEY>', '<CONTEXT_VALUE>');

// Code example
window.DATAFLUX_LOGS && window.DATAFLUX_LOGS.setGlobalContextProperty('isvip', 'xxxx');
window.DATAFLUX_LOGS && window.DATAFLUX_LOGS.setGlobalContextProperty('activity', {
    hasPaid: true,
    amount: 23.42
});

DATAFLUX_LOGS.onReady(function() {
    DATAFLUX_LOGS.setGlobalContextProperty('<CONTEXT_KEY>', '<CONTEXT_VALUE>');
})

// Code example
DATAFLUX_LOGS.onReady(function() {
    DATAFLUX_LOGS.setGlobalContextProperty('isvip', 'xxxx');
})
DATAFLUX_LOGS.onReady(function() {
    DATAFLUX_LOGS.setGlobalContextProperty('activity', {
        hasPaid: true,
        amount: 23.42
    });
})

import { datafluxLogs } from '@cloudcare/browser-logs'
datafluxLogs.setGlobalContextProperty('<CONTEXT_KEY>', <CONTEXT_VALUE>);

// Code example
datafluxLogs && datafluxLogs.setGlobalContextProperty('isvip', 'xxxx');
datafluxLogs.setGlobalContextProperty('activity', {
    hasPaid: true,
    amount: 23.42
});

Replace TAG (Overwrite)¶

CDN SyncCDN AsyncNPM

window.DATAFLUX_LOGS &&
     window.DATAFLUX_LOGS.setGlobalContext({ '<CONTEXT_KEY>': '<CONTEXT_VALUE>' });

// Code example
window.DATAFLUX_LOGS &&
     window.DATAFLUX_LOGS.setGlobalContext({
        codeVersion: 34,
    });

 window.DATAFLUX_LOGS.onReady(function() {
     window.DATAFLUX_LOGS.setGlobalContext({ '<CONTEXT_KEY>': '<CONTEXT_VALUE>' });
})

// Code example
 window.DATAFLUX_LOGS.onReady(function() {
     window.DATAFLUX_LOGS.setGlobalContext({
        codeVersion: 34,
    })
})

import { datafluxLogs } from '@cloudcare/browser-logs'

datafluxLogs.setGlobalContext({ '<CONTEXT_KEY>': '<CONTEXT_VALUE>' });

// Code example
datafluxLogs.setGlobalContext({
    codeVersion: 34,
});

Get All Set Custom TAGs¶

CDN SyncCDN AsyncNPM

var context = window.DATAFLUX_LOGS &&  window.DATAFLUX_LOGS.getGlobalContext();

 window.DATAFLUX_LOGS.onReady(function() {
    var context =  window.DATAFLUX_LOGS.getGlobalContext();
});

import { datafluxLogs } from '@cloudcare/browser-logs'

const context = datafluxLogs.getGlobalContext();

Remove Custom TAG Corresponding to a Specific Key¶

CDN SyncCDN AsyncNPM

var context = window.DATAFLUX_LOGS &&  window.DATAFLUX_LOGS.removeGlobalContextProperty('<CONTEXT_KEY>');

 window.DATAFLUX_LOGS.onReady(function() {
    var context =  window.DATAFLUX_LOGS.removeGlobalContextProperty('<CONTEXT_KEY>');
});

import { datafluxLogs } from '@cloudcare/browser-logs'

const context = datafluxLogs.removeGlobalContextProperty('<CONTEXT_KEY>');

Remove All Custom TAGs¶

CDN SyncCDN AsyncNPM

var context = window.DATAFLUX_LOGS &&  window.DATAFLUX_LOGS.clearGlobalContext();

 window.DATAFLUX_LOGS.onReady(function() {
    var context =  window.DATAFLUX_LOGS.clearGlobalContext();
});

import { datafluxLogs } from '@cloudcare/browser-logs'

const context = datafluxLogs.clearGlobalContext();

Custom User Identification¶

By default, the SDK automatically generates a unique identification ID for the user. This ID does not carry any identifying attributes and can only distinguish different user properties. Therefore, we provide additional APIs to add different identifying attributes to the current user.

Attribute	Type	Description
user.id	string	User ID
user.name	string	User nickname or username
user.email	string	User email

Note: The following attributes are optional, but it is recommended to provide at least one of them.

Add User Identification¶

CDN SyncCDN AsyncNPM

window.DATAFLUX_LOGS && window.DATAFLUX_LOGS.setUser({
    id: '1234',
    name: 'John Doe',
    email: 'john@doe.com',
})

window.DATAFLUX_LOGS.onReady(function() {
    window.DATAFLUX_LOGS.setUser({
        id: '1234',
        name: 'John Doe',
        email: 'john@doe.com',
    })
})

import { datafluxLogs } from '@cloudcare/browser-logs'
datafluxLogs.setUser({
    id: '1234',
    name: 'John Doe',
    email: 'john@doe.com',
})

Remove User Identification¶

CDN SyncCDN AsyncNPM

window.DATAFLUX_LOGS && window.DATAFLUX_LOGS.clearUser()

window.DATAFLUX_LOGS.onReady(function() {
    window.DATAFLUX_LOGS.clearUser()
})

import { datafluxLogs } from '@cloudcare/browser-logs'
datafluxLogs.clearUser()

Browser Log Collection¶

Getting Started¶

Prerequisites¶

SDK Configuration¶

NPM¶

CDN Async Loading¶

CDN Sync Loading¶

Configuration¶

Initialization Parameters¶

Usage¶

NPM¶

CDN Async¶

CDN Sync¶

Return Data Structure¶

Status Parameter¶

NPM¶

CDN Async¶

CDN Sync¶

Parameter Description¶

Custom Adding Extra Data TAGs¶

Add TAG¶

Replace TAG (Overwrite)¶

Get All Set Custom TAGs¶

Remove Custom TAG Corresponding to a Specific Key¶

Remove All Custom TAGs¶

Custom User Identification¶

Add User Identification¶

Remove User Identification¶

Is this page helpful? ×