From 3b82838b2710f9b1dbe9dc332829f8756b5305d7 Mon Sep 17 00:00:00 2001 From: Yoann Moinet Date: Thu, 27 Feb 2025 10:02:39 +0100 Subject: [PATCH] Add RUM's plugin documentation --- README.md | 85 +++++++++++++ packages/plugins/rum/README.md | 119 ++++++++++++++++++ .../tools/src/commands/integrity/readme.ts | 7 +- 3 files changed, 205 insertions(+), 6 deletions(-) create mode 100644 packages/plugins/rum/README.md diff --git a/README.md b/README.md index cd64b37c..9506bb11 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ To interact with Datadog directly from your builds. - [`customPlugins`](#customplugins) - [Features](#features) - [Error Tracking](#error-tracking-----) + - [RUM](#rum-----) - [Telemetry](#telemetry-----) - [Contributing](#contributing) - [License](#license) @@ -103,6 +104,38 @@ Follow the specific documentation for each bundler: service: string; }; }; + rum?: { // BETA, the feature may misbehave in edgiest cases. + disabled?: boolean; + sdk?: { + actionNameAttribute?: string; + allowedTracingUrls?: string[]; + allowUntrustedEvents?: boolean; + applicationId: string; + clientToken?: string; + compressIntakeRequests?: boolean; + defaultPrivacyLevel?: 'mask' | 'mask-user-input' | 'allow'; + enablePrivacyForActionName?: boolean; + env?: string; + excludedActivityUrls?: string[]; + proxy?: string; + service?: string; + sessionReplaySampleRate?: number; + sessionSampleRate?: number; + silentMultipleInit?: boolean; + site?: string; + startSessionReplayRecordingManually?: boolean; + storeContextsAcrossPages?: boolean; + telemetrySampleRate?: number; + traceSampleRate?: number; + trackingConsent?: 'granted' | 'not_granted'; + trackLongTasks?: boolean; + trackResources?: boolean; + trackUserInteractions?: boolean; + trackViewsManually?: boolean; + version?: string; + workerUrl?: string; + }; + }; telemetry?: { disabled?: boolean; enableTracing?: boolean; @@ -246,6 +279,58 @@ datadogWebpackPlugin({ +### RUM ESBuild Rollup Rspack Vite Webpack + +> [!NOTE] +> This feature is in **beta** and may misbehave in edgiest cases. +> +> Interact with Real User Monitoring (RUM) directly from your build system. + +#### [📝 Full documentation ➡️](/packages/plugins/rum#readme) + +
+ +Configuration + +```typescript +datadogWebpackPlugin({ + rum?: { // BETA, the feature may misbehave in edgiest cases. + disabled?: boolean, + sdk?: { + actionNameAttribute?: string, + allowedTracingUrls?: string[], + allowUntrustedEvents?: boolean, + applicationId: string, + clientToken?: string, + compressIntakeRequests?: boolean, + defaultPrivacyLevel?: 'mask' | 'mask-user-input' | 'allow', + enablePrivacyForActionName?: boolean, + env?: string, + excludedActivityUrls?: string[], + proxy?: string, + service?: string, + sessionReplaySampleRate?: number, + sessionSampleRate?: number, + silentMultipleInit?: boolean, + site?: string, + startSessionReplayRecordingManually?: boolean, + storeContextsAcrossPages?: boolean, + telemetrySampleRate?: number, + traceSampleRate?: number, + trackingConsent?: 'granted' | 'not_granted', + trackLongTasks?: boolean, + trackResources?: boolean, + trackUserInteractions?: boolean, + trackViewsManually?: boolean, + version?: string, + workerUrl?: string, + }, + } +}); +``` + +
+ ### Telemetry ESBuild Rollup Rspack Vite Webpack > Display and send telemetry data as metrics to Datadog. diff --git a/packages/plugins/rum/README.md b/packages/plugins/rum/README.md new file mode 100644 index 00000000..f724209b --- /dev/null +++ b/packages/plugins/rum/README.md @@ -0,0 +1,119 @@ +# RUM Plugin + +> [!NOTE] +> This feature is in **beta** and may misbehave in edgiest cases. + +Interact with Real User Monitoring (RUM) directly from your build system. + + + +## Table of content + + + + +- [Configuration](#configuration) +- [Browser SDK Injection](#browser-sdk-injection) + - [Using global `DD_RUM`](#using-global-ddrum) + - [rum.sdk.applicationId](#rumsdkapplicationid) + - [rum.sdk.clientToken](#rumsdkclienttoken) + + +## Configuration + +
+Full configuration + +```ts +rum?: { // BETA, the feature may misbehave in edgiest cases. + disabled?: boolean; + sdk?: { + actionNameAttribute?: string; + allowedTracingUrls?: string[]; + allowUntrustedEvents?: boolean; + applicationId: string; + clientToken?: string; + compressIntakeRequests?: boolean; + defaultPrivacyLevel?: 'mask' | 'mask-user-input' | 'allow'; + enablePrivacyForActionName?: boolean; + env?: string; + excludedActivityUrls?: string[]; + proxy?: string; + service?: string; + sessionReplaySampleRate?: number; + sessionSampleRate?: number; + silentMultipleInit?: boolean; + site?: string; + startSessionReplayRecordingManually?: boolean; + storeContextsAcrossPages?: boolean; + telemetrySampleRate?: number; + traceSampleRate?: number; + trackingConsent?: 'granted' | 'not_granted'; + trackLongTasks?: boolean; + trackResources?: boolean; + trackUserInteractions?: boolean; + trackViewsManually?: boolean; + version?: string; + workerUrl?: string; + }; +} +``` + +
+ +**Minimal configuration**: + +```ts +rum: { + sdk: { + applicationId: 'your_application_id', + } +} +``` + +## Browser SDK Injection + +Automatically inject the RUM SDK v6 into your application and initialize it. + +Full documentation can be found in the [Datadog documentation](https://docs.datadoghq.com/real_user_monitoring/browser/setup/client?tab=rum#configuration). + +### Using global `DD_RUM` + +You can use [the global `DD_RUM` object](https://docs.datadoghq.com/real_user_monitoring/browser/advanced_configuration/?tab=cdnasync) to interact with the RUM SDK. + +> [!NOTE] +> You don't need to use `DD_RUM.onReady()` to wrap your code, +> the plugin makes sure the SDK is loaded before executing your code. + +```ts +import type { RumTypes: { RumPublicApi } } from '@datadog/webpack-plugin'; +declare global { + type DD_RUM = RumPublicApi; +} +``` + +You can also configure `eslint` to recognize the global `DD_RUM` object: + +```json +{ + "globals": { + "DD_RUM": "readonly" + } +} +``` + +### rum.sdk.applicationId + +> required + +The RUM application ID. [Create a new application if necessary](https://app.datadoghq.com/rum/list/create). + +### rum.sdk.clientToken + +> optional, will be fetched if missing + +A [Datadog client token](https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens). + +> [!NOTE] +> If not provided, the plugin will attempt to fetch the client token using the API. +> You need to provide both `auth.apiKey` and `auth.appKey` with the `rum_apps_read` permission. diff --git a/packages/tools/src/commands/integrity/readme.ts b/packages/tools/src/commands/integrity/readme.ts index 61b6e738..a2548a9d 100644 --- a/packages/tools/src/commands/integrity/readme.ts +++ b/packages/tools/src/commands/integrity/readme.ts @@ -45,12 +45,7 @@ type BundlerMetadata = { usage: string; }; -const README_EXCEPTIONS = [ - // We decided to not publicly communicate about the rum-plugin yet. - // But we keep its sources in so it can be tested internally - // and evolve with the rest of the ecosystem. - '@dd/rum-plugin', -]; +const README_EXCEPTIONS: string[] = []; const error = red('Error|README'); // Matches image tags individually with surrounding whitespaces.