From 229685f00d25cd6b38f57513aa4f9b8624cfe6ee Mon Sep 17 00:00:00 2001 From: ruthnaebeck <19349244+ruthnaebeck@users.noreply.github.com> Date: Mon, 26 Oct 2020 13:36:59 -0400 Subject: [PATCH] DOCS-1257 Browser Log Collection single source (#8839) * DOCS-1257 Browser Log Collection single source * delete page * updates * update preview branch * remove further reading * Update local/bin/py/build/configurations/pull_config_preview.yaml --- .gitignore | 1 + .gitlab-ci.yml | 2 +- Makefile | 2 + content/en/logs/log_collection/javascript.md | 417 ------------------ .../py/build/configurations/pull_config.yaml | 13 + .../configurations/pull_config_preview.yaml | 13 + 6 files changed, 30 insertions(+), 418 deletions(-) delete mode 100644 content/en/logs/log_collection/javascript.md diff --git a/.gitignore b/.gitignore index e325091d0b6f5..8bbfbbbdb8bf1 100644 --- a/.gitignore +++ b/.gitignore @@ -67,6 +67,7 @@ npm-debug.log* # RUM content/en/real_user_monitoring/android.md content/en/real_user_monitoring/browser/_index.md +content/en/logs/log_collection/javascript.md # serverless content/en/serverless/forwarder.md diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index fc39c70b1dbac..e50b2fa273571 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -201,7 +201,7 @@ build_live: variables: CONFIG: ${LIVE_CONFIG} URL: ${LIVE_DOMAIN} - UNTRACKED_EXTRAS: "data,content/en/agent/basic_agent_usage/heroku.md,content/en/agent/basic_agent_usage/ansible.md,content/en/agent/basic_agent_usage/chef.md,content/en/agent/basic_agent_usage/puppet.md,content/en/developers/integrations,content/en/agent/basic_agent_usage/saltstack.md,content/en/developers/amazon_cloudformation.md,content/en/integrations,content/en/logs/log_collection/android.md,content/en/logs/log_collection/ios.md,content/en/tracing/setup/android.md,content/en/tracing/setup/ruby.md,content/en/security_monitoring/default_rules,content/en/serverless/forwarder.md,content/en/serverless/datadog_lambda_library/python.md,content/en/serverless/datadog_lambda_library/nodejs.md,content/en/serverless/datadog_lambda_library/ruby.md,content/en/serverless/datadog_lambda_library/go.md,content/en/serverless/datadog_lambda_library/java.md,content/en/real_user_monitoring/android.md,content/en/real_user_monitoring/browser/_index.md,content/en/serverless/serverless_integrations/plugin.md,content/en/serverless/serverless_integrations/macro.md,content/en/serverless/serverless_integrations/cli.md" + UNTRACKED_EXTRAS: "data,content/en/agent/basic_agent_usage/heroku.md,content/en/agent/basic_agent_usage/ansible.md,content/en/agent/basic_agent_usage/chef.md,content/en/agent/basic_agent_usage/puppet.md,content/en/developers/integrations,content/en/agent/basic_agent_usage/saltstack.md,content/en/developers/amazon_cloudformation.md,content/en/integrations,content/en/logs/log_collection/android.md,content/en/logs/log_collection/ios.md,content/en/tracing/setup/android.md,content/en/tracing/setup/ruby.md,content/en/security_monitoring/default_rules,content/en/serverless/forwarder.md,content/en/serverless/datadog_lambda_library/python.md,content/en/serverless/datadog_lambda_library/nodejs.md,content/en/serverless/datadog_lambda_library/ruby.md,content/en/serverless/datadog_lambda_library/go.md,content/en/serverless/datadog_lambda_library/java.md,content/en/real_user_monitoring/android.md,content/en/real_user_monitoring/browser/_index.md,content/en/serverless/serverless_integrations/plugin.md,content/en/serverless/serverless_integrations/macro.md,content/en/serverless/serverless_integrations/cli.md,content/en/logs/log_collection/javascript.md" CONFIGURATION_FILE: "./local/bin/py/build/configurations/pull_config.yaml" LOCAL: "False" script: diff --git a/Makefile b/Makefile index 3a79704dc531c..ceb779b40cc9e 100644 --- a/Makefile +++ b/Makefile @@ -131,6 +131,8 @@ clean-auto-doc: ##Remove all doc automatically created rm -f content/en/logs/log_collection/android.md ;fi @if [ content/en/logs/log_collection/ios.md ]; then \ rm -f content/en/logs/log_collection/ios.md ;fi + @if [ content/en/logs/log_collection/javascript.md ]; then \ + rm -f content/en/logs/log_collection/javascript.md ;fi @if [ content/en/tracing/setup/android.md ]; then \ rm -f content/en/tracing/setup/android.md ;fi diff --git a/content/en/logs/log_collection/javascript.md b/content/en/logs/log_collection/javascript.md deleted file mode 100644 index 2159d83ea783e..0000000000000 --- a/content/en/logs/log_collection/javascript.md +++ /dev/null @@ -1,417 +0,0 @@ ---- -title: Browser Log Collection -kind: documentation -aliases: - - /logs/log_collection/web_browser -further_reading: -- link: "https://www.npmjs.com/package/@datadog/browser-logs" - tag: "NPM" - text: "@datadog/browser-logs NPM package" -- link: "/logs/processing/" - tag: "Documentation" - text: "Learn how to process your logs" -- link: "/logs/explorer/" - tag: "Documentation" - text: "Learn how to explore your logs" ---- - -Send logs to Datadog from web browsers or other Javascript clients thanks to Datadog's `datadog-logs` client-side JavaScript logging library. - -With the `datadog-logs` library, 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. -* 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 - -1. **Get a Datadog Client Token**: For security reasons, [API keys][1] cannot be used to configure the `datadog-logs` library, as they would be exposed client-side in the JavaScript code. To collect logs from web browsers, a [client token][2] must be used. For more information about setting up a client token, see the [client token documentation][2]. -2. **Configure the Datadog browser log library** [through NPM](#npm-setup) or paste the [bundle](#bundle-setup) into the head tag directly. - -### NPM setup - -After adding [`@datadog/browser-logs`][3] to your `package.json` file, initialize it with: - -{{< site-region region="us" >}} - -```javascript -import { datadogLogs } from '@datadog/browser-logs'; - -datadogLogs.init({ - clientToken: '', - site: 'datadoghq.com', - forwardErrorsToLogs: true, - sampleRate: 100 -}); -``` - -{{< /site-region >}} -{{< site-region region="eu" >}} - -```javascript -import { datadogLogs } from '@datadog/browser-logs'; - -datadogLogs.init({ - clientToken: '', - site: 'datadoghq.eu', - forwardErrorsToLogs: true, - sampleRate: 100 -}); -``` - -{{< /site-region >}} - -### Bundle setup - -In order to not miss any logs or errors, you should load and configure the library at the beginning of the head section of your pages. - -{{< site-region region="us" >}} - -```html - - - Example to send logs to Datadog - - - - -``` - -{{< /site-region >}} -{{< site-region region="eu" >}} - -```html - - - Example to send logs to Datadog - - - - -``` - -{{< /site-region >}} - -**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library. - -### Initialization parameters - -The following parameters can be used to configure the Datadog browser log library to send logs to Datadog: - -| Parameter | Type | Required | Default | Description | -|--------------------------------|---------|----------|-----------------|----------------------------------------------------------------------------------------------------------| -| `clientToken` | String | Yes | `-` | A [Datadog Client Token][2]. | -| `site` | String | Yes | `datadoghq.com` | The Datadog Site of your organization. `datadoghq.com` for Datadog US site, `datadoghq.eu` for Datadog EU site. | -| `service` | String | No | `` | The service name for this application. | -| `env` | String | No | `` | The application’s environment e.g. prod, pre-prod, staging. | -| `version` | String | No | `` | The application’s version e.g. 1.2.3, 6c44da20, 2020.02.13. | -| `forwardErrorsToLogs` | Boolean | No | `true` | Set to `false` to stop forwarding console.error logs, uncaught exceptions and network errors to Datadog. | -| `sampleRate` | Number | No | `100` | Percentage of sessions to track. Only tracked sessions send logs. `100` for all, `0` for none of them. | -| `trackSessionAcrossSubdomains` | Boolean | No | `false` | Set to `true` to preserve session across subdomains of the same site. **If you use both Logs and RUM SDKs, this config must match.** | -| `useSecureSessionCookie` | Boolean | No | `false` | Set to `true` to use a secure session cookie. This will prevent session tracking on insecure (non-HTTPS) connections. **If you use both Logs and RUM SDKs, this config must match.** | -| `useCrossSiteSessionCookie` | Boolean | No | `false` | Set to `true` to use a secure cross-site session cookie. This will allow the Logs SDK to run when the site is loaded from another one (for example, in an `iframe`). Implies useSecureSessionCookie. **If you use both Logs and RUM SDKs, this config must match.** | - -## Send a custom log entry - -Once Datadog Browser log library is initialized, send a custom log entry directly to Datadog with the API: - -`logger.debug | info | warn | error (message: string, messageContext = Context)` - -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -import { datadogLogs } from '@datadog/browser-logs'; - -datadogLogs.logger.info('Button clicked', { name: 'buttonName', id: 123 }); -``` - -{{% /tab %}} -{{% tab "Bundle" %}} - -```javascript -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. - -{{% /tab %}} -{{< /tabs >}} - -This gives the following result: - -```json -{ - "status": "info", - "session_id": "1234", - "name": "buttonName", - "id": 123, - "message": "Button clicked", - "http": { - "url": "...", - "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.130 Safari/537.36" - }, - "network": {"client": {"ip": "109.30.xx.xxx"}} -} -``` - -The logger adds the following information by default: - -* `view.url` -* `session_id` -* `http.useragent` -* `network.client.ip` - -### Using status as a parameter - -Once Datadog Browser log library is initialized, send a custom log entry directly with its status as a parameter to Datadog with the API: - -`log (message: string, messageContext: Context, status? = 'debug' | 'info' | 'warn' | 'error')` - -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -import { datadogLogs } from '@datadog/browser-logs'; - -datadogLogs.logger.log(,,); -``` - -{{% /tab %}} -{{% tab "Bundle" %}} - -```javascript -window.DD_LOGS && DD_LOGS.logger.log(,,); -``` - -{{% /tab %}} -{{< /tabs >}} - -| Placeholder | Description | -|---------------------|-----------------------------------------------------------------------------------------| -| `` | The message of your log that is fully indexed by Datadog | -| `` | A valid JSON object that includes all attributes attached to the `` | -| `` | Status of your log; the accepted status values are `debug`, `info`, `warn`, or `error`. | - -## Advanced usage - -### Define multiple loggers - -The Datadog Browser log library contains a default logger, but it is also possible to define different loggers, which can be convenient when several teams are working on the same project - -#### Create a new logger - -Once Datadog Browser log library is initialized, use the API `createLogger` to define a new logger: - -```text -createLogger (name: string, conf?: { - level?: 'debug' | 'info' | 'warn' | 'error' - handler?: 'http' | 'console' | 'silent' - context?: Context -}) -``` - -**Note**: Those parameters can also be set with the [setLevel](#filter-by-status), [setHandler](#change-the-destination), and [setContext](#overwrite-context) APIs. - -#### Get a custom logger - -After the creation of a logger, you can access it in any part of your JavaScript code with the API: - -`getLogger (name: string)` - -#### Example - -Assume that there is a `signupLogger` logger, defined with all the other loggers: - -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -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: - -```javascript -import { datadogLogs } from '@datadog/browser-logs'; - -const signupLogger = datadogLogs.getLogger('signupLogger') -signupLogger.info('Test sign up completed') -``` - -{{% /tab %}} -{{% tab "Bundle" %}} - -```javascript -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: - -```javascript -if (window.DD_LOGS) { - const signupLogger = DD_LOGS.getLogger('signupLogger') - signupLogger.info('Test sign up completed') -} -``` - -**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library. - -{{% /tab %}} -{{< /tabs >}} - -### Overwrite context - -#### Global Context - -Once Datadog Browser log library 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. - -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -import { datadogLogs } from '@datadog/browser-logs'; - -datadogLogs.setLoggerGlobalContext("{'env': 'staging'}"); - -datadogLogs.addLoggerGlobalContext('referrer', document.referrer); -``` - -{{% /tab %}} -{{% tab "Bundle" %}} - -```javascript -window.DD_LOGS && DD_LOGS.setLoggerGlobalContext({env: 'staging'}); - -window.DD_LOGS && DD_LOGS.addLoggerGlobalContext('referrer', document.referrer); -``` - -**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library. - -{{% /tab %}} -{{< /tabs >}} - -#### Logger Context - -Once a logger is created, it is possible to: - -* Set the entire context for your logger with the `setContext (context: Context)` API. -* Add a context to your logger with `addContext (key: string, value: any)` API: - -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -import { datadogLogs } from '@datadog/browser-logs'; - -datadogLogs.setContext("{'env': 'staging'}"); - -datadogLogs.addContext('referrer', document.referrer); -``` - -{{% /tab %}} -{{% tab "Bundle" %}} - -```javascript -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. - -{{% /tab %}} -{{< /tabs >}} - -### Filter by status - -Once Datadog Browser log library is initialized, you can set the minimal log level for your logger with the API: - -`setLevel (level?: 'debug' | 'info' | 'warn' | 'error')` - -Only logs with a status equal to or higher than the specified level are sent. - -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -import { datadogLogs } from '@datadog/browser-logs'; - -datadogLogs.logger.setLevel(''); -``` - -{{% /tab %}} -{{% tab "Bundle" %}} - -```javascript -window.DD_LOGS && DD_LOGS.logger.setLevel(''); -``` - -**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library. - -{{% /tab %}} -{{< /tabs >}} - -### Change the destination - -By default, loggers created by the Datadog Browser log library are sending logs to Datadog. -Once 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`) thanks to the API: - -`setHandler (handler?: 'http' | 'console' | 'silent')` - -{{< tabs >}} -{{% tab "NPM" %}} - -```javascript -import { datadogLogs } from '@datadog/browser-logs'; - -datadogLogs.logger.setHandler(''); -``` - -{{% /tab %}} -{{% tab "Bundle" %}} - -```javascript -window.DD_LOGS && DD_LOGS.logger.setHandler(''); -``` - -**Note**: The `window.DD_LOGS` check is used to prevent issues if a loading failure occurs with the library. - -{{% /tab %}} -{{< /tabs >}} - -## Supported browsers - -The `datadog-logs` library supports all modern desktop and mobile browsers. IE10 and IE11 are also supported. - -## Further Reading - -{{< partial name="whats-next/whats-next.html" >}} - -[1]: /account_management/api-app-keys/#api-keys -[2]: /account_management/api-app-keys/#client-tokens -[3]: https://www.npmjs.com/package/@datadog/browser-logs diff --git a/local/bin/py/build/configurations/pull_config.yaml b/local/bin/py/build/configurations/pull_config.yaml index e6fce7f85bb94..58b46b2af6aa2 100644 --- a/local/bin/py/build/configurations/pull_config.yaml +++ b/local/bin/py/build/configurations/pull_config.yaml @@ -325,6 +325,19 @@ kind: documentation aliases: - /real_user_monitoring/setup + - action: pull-and-push-file + branch: master + globs: + - 'packages/logs/README.md' + options: + dest_path: '/logs/log_collection/' + file_name: 'javascript.md' + front_matters: + dependencies: ["https://github.com/DataDog/browser-sdk/blob/master/packages/logs/README.md"] + title: Browser Log Collection + kind: documentation + aliases: + - /logs/log_collection/web_browser - repo_name: datadog-cloudformation-resources contents: diff --git a/local/bin/py/build/configurations/pull_config_preview.yaml b/local/bin/py/build/configurations/pull_config_preview.yaml index e6fce7f85bb94..58b46b2af6aa2 100644 --- a/local/bin/py/build/configurations/pull_config_preview.yaml +++ b/local/bin/py/build/configurations/pull_config_preview.yaml @@ -325,6 +325,19 @@ kind: documentation aliases: - /real_user_monitoring/setup + - action: pull-and-push-file + branch: master + globs: + - 'packages/logs/README.md' + options: + dest_path: '/logs/log_collection/' + file_name: 'javascript.md' + front_matters: + dependencies: ["https://github.com/DataDog/browser-sdk/blob/master/packages/logs/README.md"] + title: Browser Log Collection + kind: documentation + aliases: + - /logs/log_collection/web_browser - repo_name: datadog-cloudformation-resources contents: