Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝 Recommend to use matching versions #615

Merged
merged 6 commits into from
Nov 16, 2020
Merged

📝 Recommend to use matching versions #615

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2f66710
📝 add warning on XHR shared data structure
bcaudan Nov 13, 2020
70ca3f1
📝 fix RUM usage + consistency in naming
bcaudan Nov 13, 2020
6943448
📝 Add note on matching version
bcaudan Nov 13, 2020
c518edc
👌 pluralize
bcaudan Nov 16, 2020
6fb4cb2
👌 phrasing
bcaudan Nov 16, 2020
a79a53b
Merge branch 'master' into bcaudan/comment
bcaudan Nov 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions packages/core/src/browser/xhrProxy.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,9 @@ function proxyXhr() {
originalXhrSend = XMLHttpRequest.prototype.send

XMLHttpRequest.prototype.open = monitor(function(this: BrowserXHR, method: string, url: string) {
// WARN: since this data structure is tied to the instance, it is shared by both logs and rum
// and can be used by different code versions depending on customer setup
// so it should stay compatible with older versions
this._datadog_xhr = {
method,
startTime: -1, // computed in send call
Expand Down
56 changes: 28 additions & 28 deletions packages/logs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Browser Log Collection

Send logs to Datadog from web browsers or other Javascript clients with the `datadog-logs` client-side JavaScript logging library.
Send logs to Datadog from web browsers or other Javascript clients with the browser logs SDK.

With the `datadog-logs` library, you can send logs directly to Datadog from JS clients and leverage the following features:
With the browser logs SDK, you can send logs directly to Datadog from JS clients and leverage the following features:

- Use the library as a logger. Everything is forwarded to Datadog as JSON documents.
- 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.
Expand All @@ -13,19 +13,19 @@ With the `datadog-logs` library, you can send logs directly to Datadog from JS c

## Setup

**Datadog client token**: For security reasons, [API keys][1] cannot be used to configure the `datadog-logs` library, because they would be exposed client-side in the JavaScript code. To collect logs from web browsers, a [client token][2] must be used. See the [client token documentation][2] for more details.
**Datadog client token**: For security reasons, [API keys][1] 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][2] must be used. See the [client token documentation][2] for more details.

**Datadog browser log library**: Configure the library through [NPM](#npm) or use the [CDN async](#cdn-async) or [CDN sync](#cdn-sync) code snippets in the head tag.
**Datadog browser logs SDK**: Configure the SDK through [NPM](#npm) or use the [CDN async](#cdn-async) or [CDN sync](#cdn-sync) code snippets in the head tag.

**Supported browsers**: The `datadog-logs` library supports all modern desktop and mobile browsers including IE10 and IE11. See the [browser support][4] table.
**Supported browsers**: The browser logs SDK supports all modern desktop and mobile browsers including IE10 and IE11. See the [browser support][4] table.

### Choose the right installation method

| Installation method | Use case |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| npm (node package manager) | This method is recommended for modern web applications. The RUM 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. |
| CDN async | This method is recommended for web applications with performance targets. The RUM 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 RUM 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. |
| 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

Expand All @@ -44,7 +44,7 @@ datadogLogs.init({

### CDN async

Load and configure the library in the head section of your pages.
Load and configure the SDK in the head section of your pages.

<!-- prettier-ignore -->
```html
Expand Down Expand Up @@ -74,7 +74,7 @@ Load and configure the library in the head section of your pages.

### CDN sync

To receive all logs and errors, load and configure the library at the beginning of the head section for your pages.
To receive all logs and errors, load and configure the SDK at the beginning of the head section for your pages.

```html
<html>
Expand All @@ -94,7 +94,7 @@ To receive all logs and errors, load and configure the library at the beginning
</html>
```

**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library.
**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the SDK.

### TypeScript

Expand All @@ -115,7 +115,7 @@ window.DD_LOGS.init({

### Initialization parameters

The following parameters are available to configure the Datadog browser log library to send logs to Datadog:
The following parameters are available to configure the Datadog browser logs SDK to send logs to Datadog:

| Parameter | Type | Required | Default | Description |
| --------------------- | ------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------- |
Expand All @@ -140,7 +140,7 @@ Options that must have a matching configuration when using the `RUM` SDK:

### Custom logs

After the Datadog browser log library is initialized, send a custom log entry directly to Datadog with the API:
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)
Expand Down Expand Up @@ -170,7 +170,7 @@ DD_LOGS.onReady(function() {
window.DD_LOGS && DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 })
```

**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library.
**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the SDK.

#### Results

Expand Down Expand Up @@ -200,7 +200,7 @@ The logger adds the following information by default:

### Status parameter

After the Datadog browser log library is initialized, send a custom log entry to Datadog with the API using the status as a 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')
Expand Down Expand Up @@ -250,11 +250,11 @@ The placeholders in the examples above are described below:

### Define multiple loggers

The Datadog browser log library contains a default logger, but it is possible to define different 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 log library is initialized, use the API `createLogger` to define a new logger:
After the Datadog browser logs SDK is initialized, use the API `createLogger` to define a new logger:

```text
createLogger (name: string, conf?: {
Expand Down Expand Up @@ -333,13 +333,13 @@ if (window.DD_LOGS) {
}
```

**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library.
**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the SDK.

### Overwrite context

#### Global context

After the Datadog browser log library is initialized, it is possible to:
After the Datadog browser logs SDK is initialized, it is possible to:

- Set the entire context for all your loggers with the `setLoggerGlobalContext (context: Context)` API.
- Add a context to all your loggers with `addLoggerGlobalContext (key: string, value: any)` API.
Expand Down Expand Up @@ -391,7 +391,7 @@ window.DD_LOGS && DD_LOGS.addLoggerGlobalContext('referrer', document.referrer)
var context = window.DD_LOGS && DD_LOGS.getLoggerGlobalContext() // => {env: 'staging', referrer: ...}
```

**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library.
**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the SDK.

#### Logger context

Expand Down Expand Up @@ -438,11 +438,11 @@ window.DD_LOGS && DD_LOGS.setContext("{'env': 'staging'}")
window.DD_LOGS && DD_LOGS.addContext('referrer', document.referrer)
```

**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library.
**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the SDK.

### Filter by status

After the Datadog browser log library is initialized, the minimal log level for your logger is set with the API:
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')
Expand Down Expand Up @@ -480,11 +480,11 @@ For CDN sync, use:
window.DD_LOGS && DD_LOGS.logger.setLevel('<LEVEL>')
```

**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library.
**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the SDK.

### Change the destination

By default, loggers created by the Datadog browser log library are sending logs to Datadog. After the Datadog browser log library is initialized, it is possible to configure the logger to send logs to the `console`, or to not send logs at all (`silent`) using to the API:
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`, or to not send logs at all (`silent`) using to the API:

```
setHandler (handler?: 'http' | 'console' | 'silent')
Expand Down Expand Up @@ -520,7 +520,7 @@ For CDN sync, use:
window.DD_LOGS && DD_LOGS.logger.setHandler('<HANDLER>')
```

**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library.
**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the SDK.

[1]: /account_management/api-app-keys/#api-keys
[2]: /account_management/api-app-keys/#client-tokens
Expand Down
10 changes: 5 additions & 5 deletions packages/rum/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,11 @@ To set up Datadog RUM browser monitoring:

### Choose the right installation method

| Installation method | Use case |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| npm (node package manager) | This method is recommended for modern web applications. The RUM 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. |
| CDN async | This method is recommended for web applications with performance targets. The RUM 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 RUM 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. |
| Installation method | Use case |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| npm (node package manager) | This method is recommended for modern web applications. The RUM 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 logs SDK if used. |
| CDN async | This method is recommended for web applications with performance targets. The RUM 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 RUM 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

Expand Down