Skip to content

Commit 750b97d

Browse files
bcaudanbcaudan
authored
[Browser RUM/Logs] add missing configuration options and APIs (#30555)
* [Browser RUM/Logs] add missing configuration options and APIs * 👌 fix wrong type
1 parent c2bcef7 commit 750b97d

File tree

3 files changed

+285
-16
lines changed

3 files changed

+285
-16
lines changed

‎content/en/logs/log_collection/javascript.md

Lines changed: 95 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ With the browser logs SDK, you can send logs directly to Datadog from web browse
1717
- Record real client IP addresses and user agents.
1818
- Optimized network usage with automatic bulk posts.
1919

20-
**Notes**:
20+
**Notes**:
2121
- **Independent of the RUM SDK**: The Browser Logs SDK can be used without the RUM SDK.
2222

2323
## Setup
@@ -406,12 +406,12 @@ The following parameters are available to configure the Datadog browser logs SDK
406406
| `sessionSampleRate` | Number | No | `100` | The percentage of sessions to track: `100` for all, `0` for none. Only tracked sessions send logs. It applies only to logs collected via the Browser Logs SDK and is independent of RUM data. |
407407
| `trackingConsent` | `"granted"` or `"not-granted"` | No | `"granted"` | Set the initial user tracking consent state. See [User Tracking Consent][15]. |
408408
| `silentMultipleInit` | Boolean | No | | Prevent logging errors while having multiple init. |
409-
| `proxy` | String | No | | Optional proxy URL (ex: `https://www.proxy.com/path`), see the full [proxy setup guide][6] for more information. |
409+
| `proxy` | String | No | | Optional proxy URL (ex: `https://www.proxy.com/path`), see the full [proxy setup guide][6] for more information. |
410+
| `usePciIntake` | Boolean | No | `false` | Use PCI-compliant intake. See [PCI DSS Compliance][20] for more information. |
410411
| `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. |
411412
| `storeContextsAcrossPages` | Boolean | No | | Store global context and user context in `localStorage` to preserve them along the user navigation. See [Contexts life cycle][11] for more details and specific limitations. |
412413
| `allowUntrustedEvents` | Boolean | No | | Allow capture of [untrusted events][13], for example in automated UI tests. |
413-
| `sendLogsAfterSessionExpiration` | Boolean | No | | Keep sending logs after the session expires.
414-
| `allowedTrackingOrigins` | Array | No | | List of origins where the SDK is allowed to run. |
414+
| `allowedTrackingOrigins` | Array | No | | List of origins where the SDK is allowed to run. |
415415

416416

417417
Options that must have a matching configuration when using the `RUM` SDK:
@@ -1042,9 +1042,97 @@ window.DD_LOGS && window.DD_LOGS.getUser() // => {}
10421042

10431043
**Note**: The `window.DD_LOGS` check prevents issues when a loading failure occurs with the SDK.
10441044

1045+
#### Account context
1046+
1047+
The Datadog logs SDK provides convenient functions to associate an `Account` with generated logs.
1048+
1049+
- Set the account for all your loggers with the `setAccount (newAccount: Account)` API.
1050+
- Add or modify an account property to all your loggers with the `setAccountProperty (key: string, value: any)` API.
1051+
- Get the currently stored account with the `getAccount ()` API.
1052+
- Remove an account property with the `removeAccountProperty (key: string)` API.
1053+
- Clear all existing account properties with the `clearAccount ()` API.
1054+
1055+
**Note**: The account context is applied before the global context. Hence, every account property included in the global context will override the account context when generating logs.
1056+
1057+
##### NPM
1058+
1059+
For NPM, use:
1060+
1061+
```javascript
1062+
import { datadogLogs } from '@datadog/browser-logs'
1063+
1064+
datadogLogs.setAccount({ id: '1234', name: 'My Company Name' })
1065+
datadogLogs.setAccountProperty('type', 'premium')
1066+
datadogLogs.getAccount() // => {id: '1234', name: 'My Company Name', type: 'premium'}
1067+
1068+
datadogLogs.removeAccountProperty('type')
1069+
datadogLogs.getAccount() // => {id: '1234', name: 'My Company Name'}
1070+
1071+
datadogLogs.clearAccount()
1072+
datadogLogs.getAccount() // => {}
1073+
```
1074+
1075+
##### CDN async
1076+
1077+
For CDN async, use:
1078+
1079+
```javascript
1080+
window.DD_LOGS.onReady(function () {
1081+
window.DD_LOGS.setAccount({ id: '1234', name: 'My Company Name' })
1082+
})
1083+
1084+
window.DD_LOGS.onReady(function () {
1085+
window.DD_LOGS.setAccountProperty('type', 'premium')
1086+
})
1087+
1088+
window.DD_LOGS.onReady(function () {
1089+
window.DD_LOGS.getAccount() // => {id: '1234', name: 'My Company Name', type: 'premium'}
1090+
})
1091+
1092+
window.DD_LOGS.onReady(function () {
1093+
window.DD_LOGS.removeAccountProperty('type')
1094+
})
1095+
1096+
window.DD_LOGS.onReady(function () {
1097+
window.DD_LOGS.getAccount() // => {id: '1234', name: 'My Company Name'}
1098+
})
1099+
1100+
window.DD_LOGS.onReady(function () {
1101+
window.DD_LOGS.clearAccount()
1102+
})
1103+
1104+
window.DD_LOGS.onReady(function () {
1105+
window.DD_LOGS.getAccount() // => {}
1106+
})
1107+
```
1108+
1109+
**Note**: Early API calls must be wrapped in the `window.DD_LOGS.onReady()` callback. This ensures the code only gets executed once the SDK is properly loaded.
1110+
1111+
##### CDN sync
1112+
1113+
For CDN sync, use:
1114+
1115+
```javascript
1116+
window.DD_LOGS && window.DD_LOGS.setAccount({ id: '1234', name: 'My Company Name' })
1117+
1118+
window.DD_LOGS && window.DD_LOGS.setAccountProperty('type', 'premium')
1119+
1120+
window.DD_LOGS && window.DD_LOGS.getAccount() // => {id: '1234', name: 'My Company Name', type: 'premium'}
1121+
1122+
window.DD_LOGS && window.DD_LOGS.removeAccountProperty('type')
1123+
1124+
window.DD_LOGS && window.DD_LOGS.getAccount() // => {id: '1234', name: 'My Company Name'}
1125+
1126+
window.DD_LOGS && window.DD_LOGS.clearAccount()
1127+
1128+
window.DD_LOGS && window.DD_LOGS.getAccount() // => {}
1129+
```
1130+
1131+
**Note**: The `window.DD_LOGS` check prevents issues when a loading failure occurs with the SDK.
1132+
10451133
#### Contexts life cycle
10461134

1047-
By default, global context and user context are stored in the current page memory, which means they are not:
1135+
By default, contexts are stored in the current page memory, which means they are not:
10481136

10491137
- kept after a full reload of the page
10501138
- shared across different tabs or windows of the same session
@@ -1325,4 +1413,5 @@ window.DD_LOGS && window.DD_LOGS.getInternalContext() // { session_id: "xxxx-xxx
13251413
[16]: https://docs.datadoghq.com/data_security/logs/#pci-dss-compliance-for-log-management
13261414
[17]: /real_user_monitoring/browser/advanced_configuration/?tab=npm#micro-frontend
13271415
[18]: /real_user_monitoring/browser/advanced_configuration/?tab=npm#enrich-and-control-rum-data
1328-
[19]: /real_user_monitoring/browser/advanced_configuration/?tab=npm#discard-a-rum-event
1416+
[19]: /real_user_monitoring/browser/advanced_configuration/?tab=npm#discard-a-rum-event
1417+
[20]: /data_security/pci_compliance/?tab=logmanagement

‎content/en/real_user_monitoring/browser/advanced_configuration.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -802,6 +802,152 @@ window.DD_RUM && window.DD_RUM.clearUser()
802802
{{% /tab %}}
803803
{{< /tabs >}}
804804
805+
## Account
806+
807+
To group users into different set, use the account concept.
808+
809+
The following attributes are available:
810+
811+
| Attribute | Type | Required | Description |
812+
|----------------|--------|----------|------------------------------------------------------------|
813+
| `account.id` | String | Yes | Unique account identifier. |
814+
| `account.name` | String | No | Account friendly name, displayed by default in the RUM UI. |
815+
816+
### Identify account
817+
818+
`datadogRum.setAccount(<ACCOUNT_CONFIG_OBJECT>)`
819+
820+
{{< tabs >}}
821+
{{% tab "NPM" %}}
822+
```javascript
823+
datadogRum.setAccount({
824+
id: '1234',
825+
name: 'My Company Name',
826+
...
827+
})
828+
```
829+
{{% /tab %}}
830+
{{% tab "CDN async" %}}
831+
```javascript
832+
window.DD_RUM.onReady(function() {
833+
window.DD_RUM.setAccount({
834+
id: '1234',
835+
name: 'My Company Name',
836+
...
837+
})
838+
})
839+
```
840+
{{% /tab %}}
841+
{{% tab "CDN sync" %}}
842+
```javascript
843+
window.DD_RUM && window.DD_RUM.setAccount({
844+
id: '1234',
845+
name: 'My Company Name',
846+
...
847+
})
848+
```
849+
850+
{{% /tab %}}
851+
{{< /tabs >}}
852+
853+
### Access account
854+
855+
`datadogRum.getAccount()`
856+
857+
{{< tabs >}}
858+
{{% tab "NPM" %}}
859+
```javascript
860+
datadogRum.getAccount()
861+
```
862+
{{% /tab %}}
863+
{{% tab "CDN async" %}}
864+
```javascript
865+
window.DD_RUM.onReady(function() {
866+
window.DD_RUM.getAccount()
867+
})
868+
```
869+
{{% /tab %}}
870+
{{% tab "CDN sync" %}}
871+
```javascript
872+
window.DD_RUM && window.DD_RUM.getAccount()
873+
```
874+
875+
{{% /tab %}}
876+
{{< /tabs >}}
877+
878+
### Add/Override account property
879+
880+
`datadogRum.setAccountProperty('<ACCOUNT_KEY>', <ACCOUNT_VALUE>)`
881+
882+
{{< tabs >}}
883+
{{% tab "NPM" %}}
884+
```javascript
885+
datadogRum.setAccountProperty('name', 'My Company Name')
886+
```
887+
{{% /tab %}}
888+
{{% tab "CDN async" %}}
889+
```javascript
890+
window.DD_RUM.onReady(function() {
891+
window.DD_RUM.setAccountProperty('name', 'My Company Name')
892+
})
893+
```
894+
{{% /tab %}}
895+
{{% tab "CDN sync" %}}
896+
```javascript
897+
window.DD_RUM && window.DD_RUM.setAccountProperty('name', 'My Company Name')
898+
```
899+
900+
{{% /tab %}}
901+
{{< /tabs >}}
902+
903+
### Remove account property
904+
905+
`datadogRum.removeAccountProperty('<ACCOUNT_KEY>')`
906+
907+
{{< tabs >}}
908+
{{% tab "NPM" %}}
909+
```javascript
910+
datadogRum.removeAccountProperty('name')
911+
```
912+
{{% /tab %}}
913+
{{% tab "CDN async" %}}
914+
```javascript
915+
window.DD_RUM.onReady(function() {
916+
window.DD_RUM.removeAccountProperty('name')
917+
})
918+
```
919+
{{% /tab %}}
920+
{{% tab "CDN sync" %}}
921+
```javascript
922+
window.DD_RUM && window.DD_RUM.removeAccountProperty('name')
923+
```
924+
{{% /tab %}}
925+
{{< /tabs >}}
926+
927+
### Clear account properties
928+
929+
`datadogRum.clearAccount()`
930+
931+
{{< tabs >}}
932+
{{% tab "NPM" %}}
933+
```javascript
934+
datadogRum.clearAccount()
935+
```
936+
{{% /tab %}}
937+
{{% tab "CDN async" %}}
938+
```javascript
939+
window.DD_RUM.onReady(function() {
940+
window.DD_RUM.clearAccount()
941+
})
942+
```
943+
{{% /tab %}}
944+
{{% tab "CDN sync" %}}
945+
```javascript
946+
window.DD_RUM && window.DD_RUM.clearAccount()
947+
```
948+
{{% /tab %}}
949+
{{< /tabs >}}
950+
805951
## Sampling
806952
807953
By default, no sampling is applied on the number of collected sessions. To apply a relative sampling (in percent) to the number of sessions collected, use the `sessionSampleRate` parameter when initializing RUM.

0 commit comments

Comments
 (0)