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¶
- 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
andsite
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.
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¶
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¶
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)¶
Get All Set Custom TAGs¶
Remove Specific Key Corresponding Custom TAG¶
Remove All Custom TAGs¶
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.