Browser Log Collection¶

Send log data of different levels (corresponding source:browser_log Metrics type log data) actively through a Web browser or Javascript client to Guance.

Custom log data collection, by integrating the SDK into the client application, collects different log data for different scenarios;
Automatically collect error information from the application (including network errors, console errors, and js errors) and report it to Guance;
Customize error levels (debug, critical, error, info, warn), customize Logger objects, and customize Log fields;
Automatically collect RUM related data and associate it with RUM business scenarios.

Getting Started¶

Prerequisites¶

DataKit: Send log data to the Guance platform via the DataKit Log Collection API;
Integrate SDK: The SDK can be integrated into the application using methods such as NPM, CDN synchronous, or CDN asynchronous;
Supported Browsers: Supports all PC and mobile browsers.

Choose Integration Method¶

Integration Method	Introduction
NPM	By bundling the SDK code into your frontend project, this method ensures no impact on the performance of the frontend page. However, requests and errors before SDK initialization may be missed.
CDN Asynchronous Loading	Through CDN accelerated caching, the SDK script is introduced asynchronously. This method ensures that the download of the SDK script does not affect the loading performance of the page, but it might miss requests and errors collected before the SDK initialization.
CDN Synchronous Loading	Through CDN accelerated caching, the SDK script is introduced synchronously. This method ensures the collection of all errors, resources, requests, and performance metrics. However, it might affect the loading performance of the page.

NPM¶

import { datafluxLogs } from '@cloudcare/browser-logs'
datafluxLogs.init({
  datakitOrigin: '<DataKit domain or IP>', // DK integration requires configuration
  clientToken: 'clientToken', // Public OpenWay integration requires filling out
  site: 'Public OpenWay address', // Public OpenWay integration requires filling out
  //service: 'browser',
  //forwardErrorsToLogs:true
})

CDN Asynchronous 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>', // DK integration requires configuration
      clientToken: 'clientToken', // Public OpenWay integration requires filling out
      site: 'Public OpenWay address', // Public OpenWay integration requires filling out
      //service: 'browser',
      //forwardErrorsToLogs:true
    })
  })
</script>

CDN Synchronous 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>', // DK integration requires configuration
      clientToken: 'clientToken', // Public OpenWay integration requires filling out
      site: 'Public OpenWay address', // Public OpenWay integration requires filling out
      //service: 'browser',
      //forwardErrorsToLogs:true
    })
</script>

Configuration¶

Initialization Parameters¶

Parameter	Type	Required	Default Value	Description
`datakitOrigin`	String	Yes		DataKit data reporting Origin Note: `protocol (including: //), domain name (or IP address) [and port number]` Example: https://www.datakit.com, http://100.20.34.3:8088.
`clientToken`	String	Yes		Data token for reporting in the openway method, obtained from the Guance console, required (public openway method access).
`site`	String	Yes		Data reporting address for public openway method, obtained from the Guance console, required (public openway method access).
`service`	String	No	`browser`	Log Service Name
`env`	String	No		Current environment of the Web application, such as Prod: production environment; Gray: gray environment; Pre: pre-release environment Common: daily environment; Local: local environment;
`version`	String	No		Version number of the Web application
`sessionSampleRate`	Number	No	`100`	Percentage of Metrics data collection: `100` means full collection, `0` means no collection
`forwardErrorsToLogs`	Boolean	No	`true`	Setting to `false` stops collecting console.error, js, and network errors reported to Guance log data
`silentMultipleInit`	Boolean	No	`false`	Does not allow multiple log objects to be initialized
`forwardConsoleLogs`	String/Array	No		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 locally in localstorage, for example: `setUser`, `addGlobalContext` api added custom data.
`storeContextsKey`	String	No		Version requirement:`>3.1.18`. Defines the key stored in localstorage, default not filled, auto-generated, this parameter mainly solves the problem of shared store under the same domain for different sub-paths

Usage¶

After initializing the SDK in the application, you can customize log data configurations via exposed JS APIs.

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 Asynchronous¶

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

CDN Synchronous¶

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

Returned 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 Asynchronous¶

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

CDN Synchronous¶

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

Parameter Description¶

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

Adding Custom TAG Data¶

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 SynchronousCDN AsynchronousNPM

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 (Override)¶

CDN SynchronousCDN AsynchronousNPM

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 SynchronousCDN AsynchronousNPM

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 Specific Key Corresponding Custom TAG¶

CDN SynchronousCDN AsynchronousNPM

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 SynchronousCDN AsynchronousNPM

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 ID for users. This ID has no identifying attributes and can only distinguish between different user properties. To address this, we provide additional APIs to add various identifying attributes to the current user.

Attribute	Type	Description
user.id	string	User ID
user.name	string	Username or Nickname
user.email	string	Email Address

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

Add User Identification¶

CDN SynchronousCDN AsynchronousNPM

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 SynchronousCDN AsynchronousNPM

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¶

Choose Integration Method¶

NPM¶

CDN Asynchronous Loading¶

CDN Synchronous Loading¶

Configuration¶

Initialization Parameters¶

Usage¶

NPM¶

CDN Asynchronous¶

CDN Synchronous¶

Returned Data Structure¶

Status Parameter¶

NPM¶

CDN Asynchronous¶

CDN Synchronous¶

Parameter Description¶

Adding Custom TAG Data¶

Add TAG¶

Replace TAG (Override)¶

Get All Set Custom TAGs¶

Remove Specific Key Corresponding Custom TAG¶

Remove All Custom TAGs¶

Custom User Identification¶

Add User Identification¶

Remove User Identification¶

Is this page helpful? ×