Browser Log Collection
Send logs to Datadog from web browser pages with the browser logs SDK.
With the browser logs SDK, you can send logs directly to Datadog from web browser pages and leverage the following features:
- Use the SDK as a logger. Everything is forwarded to Datadog as JSON documents.
- Add
context
and extra custom attributes to each log sent. - Wrap and forward every frontend error automatically.
- Forward frontend errors.
- Record real client IP addresses and user agents.
- Optimized network usage with automatic bulk posts.
Setup
Datadog client token: For security reasons, API keys cannot be used to configure the browser logs SDK, because they would be exposed client-side in the JavaScript code. To collect logs from web browsers, a client token must be used. See the client token documentation for more details.
Datadog browser logs SDK: Configure the SDK through NPM or use the CDN async or CDN sync code snippets in the head tag.
Supported browsers: The browser logs SDK supports all modern desktop and mobile browsers including IE11. See the browser support table.
Choose the right installation method
Installation method | Use case |
---|
npm (node package manager) | This method is recommended for modern web applications. The browser logs SDK gets packaged with the rest of your front-end javascript code. It has no impact on page load performance. However, the SDK might miss errors, resources and user actions triggered before the SDK is initialized. Note: it is recommended to use a matching version with RUM SDK if used. |
CDN async | This method is recommended for web applications with performance targets. The browser logs SDK is loaded from our CDN asynchronously: this method ensures the SDK download does not impact page load performance. However, the SDK might miss errors, resources and user actions triggered before the SDK is initialized. |
CDN sync | This method is recommended for collecting all RUM events. The browser logs SDK is loaded from our CDN synchronously: this method ensures the SDK is loaded first and collects all errors, resources and user actions. This method might impact page load performance. |
NPM
After adding @datadog/browser-logs
to your package.json
file, initialize it with:
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.init({
clientToken: '<DATADOG_CLIENT_TOKEN>',
site: '<DATADOG_SITE>',
forwardErrorsToLogs: true,
sessionSampleRate: 100,
})
CDN async
Load and configure the SDK in the head section of your pages.
<html>
<head>
<title>Example to send logs to Datadog</title>
<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://www.datadoghq-browser-agent.com/datadog-logs-v4.js','DD_LOGS')
DD_LOGS.onReady(function() {
DD_LOGS.init({
clientToken: 'XXX',
site: 'datadoghq.com',
forwardErrorsToLogs: true,
sessionSampleRate: 100,
})
})
</script>
</head>
</html>
Note: Early API calls must be wrapped in the DD_LOGS.onReady()
callback. This ensures the code only gets executed once the SDK is properly loaded.
CDN sync
To receive all logs and errors, load and configure the SDK at the beginning of the head section for your pages.
<html>
<head>
<title>Example to send logs to Datadog</title>
<script type="text/javascript" src="https://www.datadoghq-browser-agent.com/datadog-logs-v4.js"></script>
<script>
window.DD_LOGS &&
DD_LOGS.init({
clientToken: '<CLIENT_TOKEN>',
site: '<DATADOG_SITE>',
forwardErrorsToLogs: true,
sessionSampleRate: 100,
})
</script>
</head>
</html>
Note: The window.DD_LOGS
check prevents issues when a loading failure occurs with the SDK.
TypeScript
Types are compatible with TypeScript >= 3.8.2. For earlier versions, import JS sources and use global variables to avoid any compilation issues:
import '@datadog/browser-logs/bundle/datadog-logs'
window.DD_LOGS.init({
clientToken: '<CLIENT_TOKEN>',
site: '<DATADOG_SITE>',
forwardErrorsToLogs: true,
sessionSampleRate: 100,
})
Configuration
Initialization parameters
The following parameters are available to configure the Datadog browser logs SDK to send logs to Datadog:
Parameter | Type | Required | Default | Description |
---|
clientToken | String | Yes | | A Datadog client token. |
site | String | Yes | datadoghq.com | The Datadog site parameter of your organization. |
service | String | No | | The service name for your application. It should follow the tag syntax requirements. |
env | String | No | | The application’s environment, for example: prod, pre-prod, staging, etc. It should follow the tag syntax requirements. |
version | String | No | | The application’s version, for example: 1.2.3, 6c44da20, 2020.02.13, etc. It should follow the tag syntax requirements. |
forwardErrorsToLogs | Boolean | No | true | Set to false to stop forwarding console.error logs, uncaught exceptions and network errors to Datadog. |
forwardConsoleLogs | "all" or an Array of "log" "debug" "info" "warn" "error" | No | [] | Forward logs from console.* to Datadog. Use "all" to forward everything or an array of console API names to forward only a subset. |
forwardReports | "all" or an Array of "intervention" "deprecation" "csp_violation" | No | [] | Forward reports from the Reporting API to Datadog. Use "all" to forward everything or an array of report types to forward only a subset. |
sampleRate | Number | No | 100 | Deprecated - see sessionSampleRate . |
sessionSampleRate | Number | No | 100 | The percentage of sessions to track: 100 for all, 0 for none. Only tracked sessions send logs. |
silentMultipleInit | Boolean | No | | Prevent logging errors while having multiple init. |
proxyUrl | String | No | | Optional proxy URL (ex: https://www.proxy.com/path), see the full proxy setup guide for more information. |
telemetrySampleRate | Number | No | 20 | Telemetry data (error, debug logs) about SDK execution is sent to Datadog in order to detect and solve potential issues. Set this option to 0 to opt out from telemetry collection. |
Options that must have a matching configuration when using the RUM
SDK:
Parameter | Type | Required | Default | Description |
---|
trackSessionAcrossSubdomains | Boolean | No | false | Preserve the session across subdomains for the same site. |
useSecureSessionCookie | Boolean | No | false | Use a secure session cookie. This disables logs sent on insecure (non-HTTPS) connections. |
useCrossSiteSessionCookie | Boolean | No | false | Use a secure cross-site session cookie. This allows the logs SDK to run when the site is loaded from another one (iframe). Implies useSecureSessionCookie . |
Usage
Custom logs
After the Datadog browser logs SDK is initialized, send a custom log entry directly to Datadog with the API:
logger.debug | info | warn | error (message: string, messageContext = Context)
NPM
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.logger.info('Button clicked', { name: 'buttonName', id: 123 })
CDN async
DD_LOGS.onReady(function () {
DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 })
})
Note: Early API calls must be wrapped in the DD_LOGS.onReady()
callback. This ensures the code only gets executed once the SDK is properly loaded.
CDN sync
window.DD_LOGS && DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 })
Note: The window.DD_LOGS
check prevents issues when a loading failure occurs with the SDK.
Results
The results are the same when using NPM, CDN async or CDN sync:
{
"status": "info",
"session_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "buttonName",
"id": 123,
"message": "Button clicked",
"date": 1234567890000,
"origin": "logger",
"http": {
"useragent": "Mozilla/5.0 ...",
},
"view": {
"url": "https://...",
"referrer": "https://...",
},
"network": {
"client": {
"geoip": {...}
"ip": "xxx.xxx.xxx.xxx"
}
}
}
The Logs SDK adds the following information by default (more fields can be added if the RUM SDK is
present):
date
view.url
view.referrer
session_id
(only if a session is used)
The Datadog backend adds more fields, like:
http.useragent
network.client.ip
Status parameter
After the Datadog browser logs SDK is initialized, send a custom log entry to Datadog with the API using the status as a parameter:
log (message: string, messageContext: Context, status? = 'debug' | 'info' | 'warn' | 'error')
NPM
For NPM, use:
import { datadogLogs } from '@datadog/browser-logs';
datadogLogs.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);
CDN async
For CDN async, use:
DD_LOGS.onReady(function() {
DD_LOGS.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);
})
Note: Early API calls must be wrapped in the DD_LOGS.onReady()
callback. This ensures the code only gets executed once the SDK is properly loaded.
CDN sync
For CDN sync, use:
window.DD_LOGS && DD_LOGS.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);
Placeholders
The placeholders in the examples above are described below:
Placeholder | Description |
---|
<MESSAGE> | The message of your log that is fully indexed by Datadog. |
<JSON_ATTRIBUTES> | A valid JSON object, which includes all attributes attached to the <MESSAGE> . |
<STATUS> | The status of your log; accepted status values are debug , info , warn , or error . |
Advanced usage
Scrub sensitive data from your Browser logs
If your Browser logs contain sensitive information that needs redacting, configure the Browser SDK to scrub sensitive sequences by using the beforeSend
callback when you initialize the Browser Log Collector.
The beforeSend
callback function gives you access to each log collected by the Browser SDK before it is sent to Datadog, and lets you update any property.
To redact email addresses from your web application URLs:
NPM
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.init({
...,
beforeSend: (log) => {
log.view.url = log.view.url.replace(/email=[^&]*/, "email=REDACTED")
},
...
});
CDN Async
DD_LOGS.onReady(function() {
DD_LOGS.init({
...,
beforeSend: (log) => {
log.view.url = log.view.url.replace(/email=[^&]*/, "email=REDACTED")
},
...
})
})
CDN Sync
window.DD_LOGS &&
window.DD_LOGS.init({
...,
beforeSend: (log) => {
log.view.url = log.view.url.replace(/email=[^&]*/, "email=REDACTED")
},
...
});
The following properties are automatically collected by the SDK and could contain sensitive data:
Attribute | Type | Description |
---|
view.url | String | The URL of the active web page. |
view.referrer | String | The URL of the previous web page from which a link to the currently requested page was followed. |
message | String | The content of the log. |
error.stack | String | The stack trace or complementary information about the error. |
http.url | String | The HTTP URL. |
Discard specific logs
The beforeSend
callback function allows you to also discard a log before it is sent to Datadog.
To discard network errors if their status is 404:
NPM
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.init({
...,
beforeSend: (log) => {
if (log.http && log.http.status_code === 404) {
return false
}
},
...
});
CDN Async
DD_LOGS.onReady(function() {
DD_LOGS.init({
...,
beforeSend: (log) => {
if (log.http && log.http.status_code === 404) {
return false
}
},
...
})
})
CDN Sync
window.DD_LOGS &&
window.DD_LOGS.init({
...,
beforeSend: (log) => {
if (log.http && log.http.status_code === 404) {
return false
}
},
...
});
Define multiple loggers
The Datadog browser logs SDK contains a default logger, but it is possible to define different loggers.
Create a new logger
After the Datadog browser logs SDK is initialized, use the API createLogger
to define a new logger:
createLogger (name: string, conf?: {
level?: 'debug' | 'info' | 'warn' | 'error',
handler?: 'http' | 'console' | 'silent',
context?: Context
})
Note: These parameters can be set with the setLevel, setHandler, and setContext APIs.
Get a custom logger
After the creation of a logger, access it in any part of your JavaScript code with the API:
getLogger(name: string)
NPM
For example, assume there is a signupLogger
, defined with all the other loggers:
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.createLogger('signupLogger', 'info', 'http', { env: 'staging' })
It can now be used in a different part of the code with:
import { datadogLogs } from '@datadog/browser-logs'
const signupLogger = datadogLogs.getLogger('signupLogger')
signupLogger.info('Test sign up completed')
CDN async
For example, assume there is a signupLogger
, defined with all the other loggers:
DD_LOGS.onReady(function () {
const signupLogger = DD_LOGS.createLogger('signupLogger', 'info', 'http', { env: 'staging' })
})
It can now be used in a different part of the code with:
DD_LOGS.onReady(function () {
const signupLogger = DD_LOGS.getLogger('signupLogger')
signupLogger.info('Test sign up completed')
})
Note: Early API calls must be wrapped in the DD_LOGS.onReady()
callback. This ensures the code only gets executed once the SDK is properly loaded.
CDN sync
For example, assume there is a signupLogger
, defined with all the other loggers:
if (window.DD_LOGS) {
const signupLogger = DD_LOGS.createLogger('signupLogger', 'info', 'http', { env: 'staging' })
}
It can now be used in a different part of the code with:
if (window.DD_LOGS) {
const signupLogger = DD_LOGS.getLogger('signupLogger')
signupLogger.info('Test sign up completed')
}
Note: The window.DD_LOGS
check prevents issues when a loading failure occurs with the SDK.
Overwrite context
Global context
After the Datadog browser logs SDK is initialized, it is possible to:
- Set the entire context for all your loggers with the
setGlobalContext (context: object)
API. - Add a context to all your loggers with the
setGlobalContextProperty (key: string, value: any)
API. - Get the entire global context with the
getGlobalContext ()
API. - Remove context property with the
removeGlobalContextProperty (key: string)
API. - Clear all existing context properties with the
clearGlobalContext ()
API.
The Log Browser SDK v4.17.0 has updated the names of several APIs:
getGlobalContext
instead of getLoggerGlobalContext
setGlobalContext
instead of setLoggerGlobalContext
setGlobalContextProperty
instead of addLoggerGlobalContext
removeGlobalContextProperty
instead of removeLoggerGlobalContext
NPM
For NPM, use:
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.setGlobalContext({ env: 'staging' })
datadogLogs.setGlobalContextProperty('referrer', document.referrer)
datadogLogs.getGlobalContext()
datadogLogs.removeGlobalContextProperty('referrer')
datadogLogs.getGlobalContext()
datadogLogs.clearGlobalContext()
datadogLogs.getGlobalContext()
CDN async
For CDN async, use:
DD_LOGS.onReady(function () {
DD_LOGS.setGlobalContext({ env: 'staging' })
})
DD_LOGS.onReady(function () {
DD_LOGS.setGlobalContextProperty('referrer', document.referrer)
})
DD_LOGS.onReady(function () {
DD_LOGS.getGlobalContext()
})
DD_LOGS.onReady(function () {
DD_LOGS.removeGlobalContextProperty('referrer')
})
DD_LOGS.onReady(function () {
DD_LOGS.getGlobalContext()
})
DD_LOGS.onReady(function () {
DD_LOGS.clearGlobalContext()
})
DD_LOGS.onReady(function () {
DD_LOGS.getGlobalContext()
})
Note: Early API calls must be wrapped in the DD_LOGS.onReady()
callback. This ensures the code only gets executed once the SDK is properly loaded.
CDN sync
For CDN sync, use:
window.DD_LOGS && DD_LOGS.setGlobalContext({ env: 'staging' })
window.DD_LOGS && DD_LOGS.setGlobalContextProperty('referrer', document.referrer)
window.DD_LOGS && DD_LOGS.getGlobalContext()
window.DD_LOGS && DD_LOGS.removeGlobalContextProperty('referrer')
window.DD_LOGS && DD_LOGS.getGlobalContext()
window.DD_LOGS && DD_LOGS.clearGlobalContext()
window.DD_LOGS && DD_LOGS.getGlobalContext()
Note: The window.DD_LOGS
check prevents issues when a loading failure occurs with the SDK.
User context
The Datadog logs SDK provides convenient functions to associate a User
with generated logs.
- Set the user for all your loggers with the
setUser (newUser: User)
API. - Add or modify a user property to all your loggers with the
setUserProperty (key: string, value: any)
API. - Get the currently stored user with the
getUser ()
API. - Remove a user property with the
removeUserProperty (key: string)
API. - Clear all existing user properties with the
clearUser ()
API.
Note: The user context is applied before the global context. Hence, every user property included in the global context will override the user context when generating logs.
NPM
For NPM, use:
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.setUser({ id: '1234', name: 'John Doe', email: 'john@doe.com' })
datadogLogs.setUserProperty('type', 'customer')
datadogLogs.getUser()
datadogLogs.removeUserProperty('type')
datadogLogs.getUser()
datadogLogs.clearUser()
datadogLogs.getUser()
CDN async
For CDN async, use:
DD_LOGS.onReady(function () {
DD_LOGS.setUser({ id: '1234', name: 'John Doe', email: 'john@doe.com' })
})
DD_LOGS.onReady(function () {
DD_LOGS.setUserProperty('type', 'customer')
})
DD_LOGS.onReady(function () {
DD_LOGS.getUser()
})
DD_LOGS.onReady(function () {
DD_LOGS.removeUserProperty('type')
})
DD_LOGS.onReady(function () {
DD_LOGS.getUser()
})
DD_LOGS.onReady(function () {
DD_LOGS.clearUser()
})
DD_LOGS.onReady(function () {
DD_LOGS.getUser()
})
Note: Early API calls must be wrapped in the DD_LOGS.onReady()
callback. This ensures the code only gets executed once the SDK is properly loaded.
CDN sync
For CDN sync, use:
window.DD_LOGS && DD_LOGS.setUser({ id: '1234', name: 'John Doe', email: 'john@doe.com' })
window.DD_LOGS && DD_LOGS.setUserProperty('type', 'customer')
window.DD_LOGS && DD_LOGS.getUser()
window.DD_LOGS && DD_LOGS.removeUserProperty('type')
window.DD_LOGS && DD_LOGS.getUser()
window.DD_LOGS && DD_LOGS.clearUser()
window.DD_LOGS && DD_LOGS.getUser()
Note: The window.DD_LOGS
check prevents issues when a loading failure occurs with the SDK.
Logger context
After a logger is created, it is possible to:
- Set the entire context for your logger with the
setContext (context: object)
API. - Add a context to your logger with
addContext (key: string, value: any)
API:
NPM
For NPM, use:
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.setContext("{'env': 'staging'}")
datadogLogs.addContext('referrer', document.referrer)
CDN async
For CDN async, use:
DD_LOGS.onReady(function () {
DD_LOGS.setContext("{'env': 'staging'}")
})
DD_LOGS.onReady(function () {
DD_LOGS.addContext('referrer', document.referrer)
})
Note: Early API calls must be wrapped in the DD_LOGS.onReady()
callback. This ensures the code only gets executed once the SDK is properly loaded.
CDN sync
For CDN sync, use:
window.DD_LOGS && DD_LOGS.setContext("{'env': 'staging'}")
window.DD_LOGS && DD_LOGS.addContext('referrer', document.referrer)
Note: The window.DD_LOGS
check prevents issues when a loading failure occurs with the SDK.
Filter by status
After the Datadog browser logs SDK is initialized, the minimal log level for your logger is set with the API:
setLevel (level?: 'debug' | 'info' | 'warn' | 'error')
Only logs with a status equal to or higher than the specified level are sent.
NPM
For NPM, use:
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.logger.setLevel('<LEVEL>')
CDN async
For CDN async, use:
DD_LOGS.onReady(function () {
DD_LOGS.logger.setLevel('<LEVEL>')
})
Note: Early API calls must be wrapped in the DD_LOGS.onReady()
callback. This ensures the code only gets executed once the SDK is properly loaded.
CDN sync
For CDN sync, use:
window.DD_LOGS && DD_LOGS.logger.setLevel('<LEVEL>')
Note: The window.DD_LOGS
check prevents issues when a loading failure occurs with the SDK.
Change the destination
By default, loggers created by the Datadog browser logs SDK are sending logs to Datadog. After the Datadog browser logs SDK is initialized, it is possible to configure the logger to:
- send logs to the
console
and Datadog (http
) - send logs to the
console
only - not send logs at all (
silent
)
setHandler (handler?: 'http' | 'console' | 'silent' | Array<handler>)
NPM
For NPM, use:
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.logger.setHandler('<HANDLER>')
datadogLogs.logger.setHandler(['<HANDLER1>', '<HANDLER2>'])
CDN async
For CDN async, use:
DD_LOGS.onReady(function () {
DD_LOGS.logger.setHandler('<HANDLER>')
DD_LOGS.logger.setHandler(['<HANDLER1>', '<HANDLER2>'])
})
Note: Early API calls must be wrapped in the DD_LOGS.onReady()
callback. This ensures the code only gets executed once the SDK is properly loaded.
CDN sync
For CDN sync, use:
window.DD_LOGS && DD_LOGS.logger.setHandler('<HANDLER>')
window.DD_LOGS && DD_LOGS.logger.setHandler(['<HANDLER1>', '<HANDLER2>'])
Note: The window.DD_LOGS
check prevents issues when a loading failure occurs with the SDK.
Access internal context
After the Datadog browser logs SDK is initialized, you can access the internal context of the SDK. This allows you to access the session_id
.
getInternalContext (startTime?: 'number' | undefined)
You can optionally use startTime
parameter to get the context of a specific time. If the parameter is omitted, the current context is returned.
NPM
For NPM, use:
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.getInternalContext()
CDN async
For CDN async, use:
DD_LOGS.onReady(function () {
DD_LOGS.getInternalContext()
})
CDN sync
For CDN sync, use:
window.DD_LOGS && window.DD_LOGS.getInternalContext()