Browser Log Collection¶

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

Custom log data collection, integrate SDK into client applications, collect different log data for different scenarios.
Automatically collect error information from the application end (including network errors, console errors, and js errors) and report them to Guance.
Custom error levels (debug,critical,error,info,warn), custom Logger objects, and custom Log fields.
Automatically collect RUM related data, associate with RUM business scenarios.

Getting Started¶

Prerequisites¶

DataKit AccessPublic OpenWay

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

Obtain clientToken and site parameters from the console.
When integrating the SDK, there is no need to configure datakitOrigin, data will be sent to the public DataWay by default.

SDK Configuration¶

Access Method	Introduction
NPM	By bundling the SDK code with your front-end project, this method ensures that there is no impact on the performance of the front-end page, but may miss requests and errors before SDK initialization.
CDN Asynchronous	Introduce the SDK script asynchronously through CDN acceleration caching, this method ensures that the download of the SDK script does not affect the loading performance of the page, but may miss requests and errors before SDK initialization.
CDN Synchronous	Introduce the SDK script synchronously through CDN acceleration caching, this method ensures that all errors, resources, requests, and performance metrics can be collected. However, it may affect the loading performance of the page.

NPM¶

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

CDN Asynchronous¶

<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
      clientToken: "clientToken", // Required for public OpenWay access
      site: "Public OpenWay Address", // Required for public OpenWay access
      //service: 'browser',
      //forwardErrorsToLogs:true
    })
  })
</script>

CDN Synchronous¶

<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
      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 (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: 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 metric data collection: `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`	Do not allow multiple log objects to be initialized
`forwardConsoleLogs`	String/Array			Types of browser console logs to collect, options: `error`, `log`, `info`, `warn`, `error`
`storeContextsToLocal`	Boolean	No		Version requirement:`>3.1.2`. Whether to cache user-defined data locally in localstorage, e.g., custom data added by `setUser`, `addGlobalContext` APIs.
`storeContextsKey`	String	No		Version requirement:`>3.1.18`. Define the key stored in localstorage, default is empty, automatically generated, this parameter is mainly to distinguish the problem of sharing store under the same domain but different subpaths.

Usage¶

After initializing the SDK in the application, you can customize the log data 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 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 })

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

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>`	Guance log Message field
`<JSON_ATTRIBUTES>`	Additional data describing the Message, a Json object
`<STATUS>`	Log level, options `debug`,`info`,`warn`,`error`,`critical`

Custom Adding Extra Data TAG¶

After initializing the 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 (Overwrite)¶

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 identifier ID for the user. This ID does not carry any identifying attributes and can only distinguish different user attributes. For this reason, 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 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¶

SDK Configuration¶

NPM¶

CDN Asynchronous¶

CDN Synchronous¶

Configuration¶

Initialization Parameters¶

Usage¶

NPM¶

CDN Asynchronous¶

CDN Synchronous¶

Return Data Structure¶

Status Parameters¶

NPM¶

CDN Asynchronous¶

CDN Synchronous¶

Parameter Description¶

Custom Adding Extra Data TAG¶

Add TAG¶

Replace TAG (Overwrite)¶

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? ×