diff --git a/packages/logs/README.md b/packages/logs/README.md index 0d1828743e..c6d6a63826 100644 --- a/packages/logs/README.md +++ b/packages/logs/README.md @@ -23,7 +23,7 @@ With the browser logs SDK, you can send logs directly to Datadog from web browse | 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. | +| 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. | @@ -70,7 +70,7 @@ Load and configure the SDK in the head section of your pages. ``` -**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. +**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 @@ -148,7 +148,7 @@ Options that must have a matching configuration when using the `RUM` SDK: 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) +logger.debug | info | warn | error (message: string, messageContext?: Context, error?: Error) ``` #### NPM @@ -167,7 +167,7 @@ DD_LOGS.onReady(function () { }) ``` -**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. +**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 @@ -179,7 +179,7 @@ window.DD_LOGS && DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id #### Results -The results are the same when using NPM, CDN async or CDN sync: +The results are the same when using NPM, CDN async, or CDN sync: ```json { @@ -219,12 +219,84 @@ The Datadog backend adds more fields, like: - `http.useragent` - `network.client.ip` -### Status parameter +### Error tracking -After the Datadog browser logs SDK is initialized, send a custom log entry to Datadog with the API using the status as a parameter: +The Datadog browser logs SDK allows for manual error tracking by using the optional `error` parameter (Available in SDK v4.36.0+). When an instance of a [JavaScript Error][10] is provided, the SDK extracts relevant information (kind, message, stack trace) from the error. ``` -log (message: string, messageContext: Context, status? = 'debug' | 'info' | 'warn' | 'error') +logger.debug | info | warn | error (message: string, messageContext?: Context, error?: Error) +``` + +#### NPM + +```javascript +import { datadogLogs } from '@datadog/browser-logs' + +try { + ... + throw new Error('Wrong behavior') + ... +} catch (ex) { + datadogLogs.logger.error('Error occurred', {}, ex) +} +``` + +#### CDN async + +```javascript +try { + ... + throw new Error('Wrong behavior') + ... +} catch (ex) { + DD_LOGS.onReady(function () { + DD_LOGS.logger.error('Error occurred', {}, ex) + }) +} +``` + +**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 + +```javascript +try { + ... + throw new Error('Wrong behavior') + ... +} catch (ex) { + window.DD_LOGS && DD_LOGS.logger.error('Error occurred', {}, ex) +} +``` + +**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: + +```json +{ + "status": "error", + "session_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "message": "Error occurred", + "date": 1234567890000, + "origin": "logger", + "error" : { + "message": "Wrong behavior", + "kind" : "Error", + "stack" : "Error: Wrong behavior at @ :1:1" + }, + ... +} +``` + +### Generic logger function + +The Datadog browser logs SDK adds shorthand functions (`.debug`, `.info`, `.warn`, `.error`) to the loggers for convenience. A generic logger function is also available, exposing the `status` parameter: + +``` +log (message: string, messageContext?: Context, status? = 'debug' | 'info' | 'warn' | 'error', error?: Error) ``` #### NPM @@ -234,7 +306,7 @@ For NPM, use: ```javascript import { datadogLogs } from '@datadog/browser-logs'; -datadogLogs.logger.log(,,); +datadogLogs.logger.log(,,,); ``` #### CDN async @@ -243,18 +315,18 @@ For CDN async, use: ```javascript DD_LOGS.onReady(function() { - DD_LOGS.logger.log(,,); + DD_LOGS.logger.log(,,,); }) ``` -**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. +**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: ```javascript -window.DD_LOGS && DD_LOGS.logger.log(,,); +window.DD_LOGS && DD_LOGS.logger.log(,,,); ``` #### Placeholders @@ -266,6 +338,7 @@ The placeholders in the examples above are described below: | `` | The message of your log that is fully indexed by Datadog. | | `` | A valid JSON object, which includes all attributes attached to the ``. | | `` | The status of your log; accepted status values are `debug`, `info`, `warn`, or `error`. | +| `` | An instance of a [JavaScript Error][10] object. | ## Advanced usage @@ -451,7 +524,7 @@ DD_LOGS.onReady(function () { }) ``` -**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. +**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 @@ -549,7 +622,7 @@ DD_LOGS.onReady(function () { }) ``` -**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. +**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 @@ -637,7 +710,7 @@ DD_LOGS.onReady(function () { }) ``` -**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. +**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 @@ -694,7 +767,7 @@ DD_LOGS.onReady(function () { }) ``` -**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. +**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 @@ -738,7 +811,7 @@ DD_LOGS.onReady(function () { }) ``` -**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. +**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 @@ -784,7 +857,7 @@ DD_LOGS.onReady(function () { }) ``` -**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. +**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 @@ -846,3 +919,4 @@ window.DD_LOGS && window.DD_LOGS.getInternalContext() // { session_id: "xxxx-xxx [7]: https://docs.datadoghq.com/getting_started/tagging/#defining-tags [8]: https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API [9]: https://docs.datadoghq.com/getting_started/site/ +[10]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error