feat(replay): Deprecate privacy options in favor of a new API, remove some recording options #6645
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -83,17 +83,20 @@ Sentry.setUser({ email: "[email protected]" }); | |
|
|
||
| ### Stopping & re-starting replays | ||
|
|
||
| Replay recording only starts when it is included in the `integrations` array when calling `Sentry.init` or calling `addIntegration` from the a Sentry client instance. To stop recording you can call the `stop()`. | ||
|
|
||
| ```js | ||
| const replay = new Replay(); | ||
| Sentry.init({ | ||
| integrations: [replay] | ||
| }); | ||
|
|
||
| const client = getClient(); | ||
|
|
||
| // Add replay integration, will start recoring | ||
| client.addIntegration(replay); | ||
|
|
||
| replay.stop(); // Stop recording | ||
| ``` | ||
|
|
||
| ## Loading Replay as a CDN Bundle | ||
|
|
@@ -185,19 +188,29 @@ The following options can be configured as options to the integration, in `new R | |
|
|
||
| The following options can be configured as options to the integration, in `new Replay({})`: | ||
|
|
||
| | key | type | default | description | | ||
| | ---------------- | ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | maskAllText | boolean | `true` | Mask _all_ text content. Will pass text content through `maskTextFn` before sending to server. | | ||
| | maskAllInputs | boolean | `true` | Mask values of `<input>` elements. Passes input values through `maskInputFn` before sending to server. | | ||
| | blockAllMedia | boolean | `true` | Block _all_ media elements (`img, svg, video, object, picture, embed, map, audio`) | ||
| | maskTextFn | (text: string) => string | `(text) => '*'.repeat(text.length)` | Function to customize how text content is masked before sending to server. By default, masks text with `*`. | | ||
| | block | Array<string> | `.sentry-block, [data-sentry-block]` | Redact any elements that match the DOM selectors. See [privacy](#blocking) section for an example. | | ||
| | unblock | Array<string> | `.sentry-unblock, [data-sentry-unblock]`| Do not redact any elements that match the DOM selectors. Useful when using `blockAllMedia`. See [privacy](#blocking) section for an example. | | ||
| | mask | Array<string> | `.sentry-mask, [data-sentry-mask]` | Mask all elements that match the given DOM selectors. See [privacy](#masking) section for an example. | | ||
| | unmask | Array<string> | `.sentry-unmask, [data-sentry-unmask]` | Unmask all elements that match the given DOM selectors. Useful when using `maskAllText`. See [privacy](#masking) section for an example. | | ||
| | ignore | Array<string> | `.sentry-ignore, [data-sentry-ignore]` | Ignores all events on the matching input fields. See [privacy](#ignoring) section for an example. | | ||
|
|
||
| #### Deprecated options | ||
| In order to streamline our privacy options, the following have been deprecated in favor for the respective options above. | ||
|
|
||
| | deprecated key | replaced by | description | | ||
| | ---------------- | ----------- | ----------- | | ||
| | maskInputOptions | mask | Use CSS selectors in `mask` in order to mask all inputs of a certain type. For example, `input[type="address"]` | | ||
| | blockSelector | block | The selector(s) can be moved directly in the `block` array. | | ||
| | blockClass | block | Convert the class name to a CSS selector and add to `block` array. For example, `first-name` becomes `.first-name`. Regexes can be moved as-is. | | ||
| | maskClass | mask | Convert the class name to a CSS selector and add to `mask` array. For example, `first-name` becomes `.first-name`. Regexes can be moved as-is. | | ||
| | maskSelector | mask | The selector(s) can be moved directly in the `mask` array. | | ||
| | ignoreClass | ignore | Convert the class name to a CSS selector and add to `ignore` array. For example, `first-name` becomes `.first-name`. Regexes can be moved as-is. | | ||
|
|
||
| ## Privacy | ||
| There are several ways to deal with PII. By default, the integration will mask all text content with `*` and block all media elements (`img, svg, video, object, picture, embed, map, audio`). This can be disabled by setting `maskAllText` to `false`. It is also possible to add the following CSS classes to specific DOM elements to prevent recording its contents: `sentry-block`, `sentry-ignore`, and `sentry-mask`. The following sections will show examples of how content is handled by the differing methods. | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -113,10 +113,70 @@ export interface ReplayPluginOptions extends SessionOptions { | |
| }>; | ||
| } | ||
|
|
||
| export interface ReplayIntegrationPrivacyOptions { | ||
| /** | ||
| * Mask text content for elements that match the CSS selectors in the list. | ||
| */ | ||
| mask?: string[]; | ||
|
|
||
| /** | ||
| * Unmask text content for elements that match the CSS selectors in the list. | ||
| */ | ||
| unmask?: string[]; | ||
|
|
||
| /** | ||
| * Block elements that match the CSS selectors in the list. Blocking replaces | ||
| * the element with an empty placeholder with the same dimensions. | ||
| */ | ||
| block?: string[]; | ||
|
|
||
| /** | ||
| * Unblock elements that match the CSS selectors in the list. This is useful when using `blockAllMedia`. | ||
| */ | ||
| unblock?: string[]; | ||
|
|
||
| /** | ||
| * Ignore input events for elements that match the CSS selectors in the list. | ||
| */ | ||
| ignore?: string[]; | ||
|
There was a problem hiding this comment. should we go with There was a problem hiding this comment. @mydea hmm my worry is that people will confuse it for DOM events e.g. clicks? |
||
|
|
||
| /** | ||
| * A callback function to customize how your text is masked. | ||
| */ | ||
| maskFn?: Pick<RecordingOptions, 'maskTextFn'>; | ||
|
There was a problem hiding this comment. Just thinking, do we need to expose this? Or is it OK to just not allow to configure this? There was a problem hiding this comment. I'm thinking we should keep it since we are being so aggressive about privacy first |
||
| } | ||
|
|
||
| // These are optional for ReplayPluginOptions because the plugin sets default values | ||
| type OptionalReplayPluginOptions = Partial<ReplayPluginOptions>; | ||
|
|
||
| export interface DeprecatedPrivacyOptions { | ||
| /** | ||
| * @deprecated Use `block` which accepts an array of CSS selectors | ||
| */ | ||
| blockSelector?: RecordingOptions['blockSelector']; | ||
| /** | ||
| * @deprecated Use `block` which accepts an array of CSS selectors | ||
| */ | ||
| blockClass?: RecordingOptions['blockClass']; | ||
| /** | ||
| * @deprecated Use `mask` which accepts an array of CSS selectors | ||
| */ | ||
| maskTextClass?: RecordingOptions['maskTextClass']; | ||
| /** | ||
| * @deprecated Use `mask` which accepts an array of CSS selectors | ||
| */ | ||
| maskTextSelector?: RecordingOptions['maskTextSelector']; | ||
| /** | ||
| * @deprecated Use `ignore` which accepts an array of CSS selectors | ||
| */ | ||
| ignoreClass?: RecordingOptions['ignoreClass']; | ||
| } | ||
|
|
||
| export interface ReplayConfiguration | ||
| extends ReplayIntegrationPrivacyOptions, | ||
| OptionalReplayPluginOptions, | ||
| DeprecatedPrivacyOptions, | ||
| Pick<RecordingOptions, 'maskAllInputs'> {} | ||
|
|
||
| interface CommonEventContext { | ||
| /** | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| import type { DeprecatedPrivacyOptions, ReplayIntegrationPrivacyOptions } from '../types'; | ||
|
|
||
| type GetPrivacyOptions = Required<Omit<ReplayIntegrationPrivacyOptions, 'maskFn'>> & DeprecatedPrivacyOptions; | ||
| interface GetPrivacyReturn { | ||
| maskTextSelector: string; | ||
| unmaskTextSelector: string; | ||
| maskInputSelector: string; | ||
| unmaskInputSelector: string; | ||
| blockSelector: string; | ||
| unblockSelector: string; | ||
| ignoreSelector: string; | ||
|
|
||
| blockClass?: RegExp; | ||
| maskTextClass?: RegExp; | ||
| } | ||
|
|
||
| function getOption( | ||
| selectors: string[], | ||
| defaultSelectors: string[], | ||
| deprecatedClassOption?: string | RegExp, | ||
| deprecatedSelectorOption?: string, | ||
| ): string { | ||
| const deprecatedSelectors = typeof deprecatedSelectorOption === 'string' ? deprecatedSelectorOption.split(',') : []; | ||
|
|
||
| const allSelectors = [ | ||
| ...selectors, | ||
| // @deprecated | ||
| ...deprecatedSelectors, | ||
|
|
||
| // sentry defaults | ||
| ...defaultSelectors, | ||
| ]; | ||
|
|
||
| // @deprecated | ||
| if (typeof deprecatedClassOption !== 'undefined') { | ||
| // NOTE: No support for RegExp | ||
| if (typeof deprecatedClassOption === 'string') { | ||
| allSelectors.push(`.${deprecatedClassOption}`); | ||
| } | ||
|
|
||
| // eslint-disable-next-line no-console | ||
| console.warn( | ||
| '[Replay] You are using a deprecated configuration item for privacy. Read the documentation on how to use the new privacy configuration.', | ||
| ); | ||
| } | ||
|
|
||
| return allSelectors.join(','); | ||
| } | ||
|
|
||
| /** | ||
| * Returns privacy related configuration for use in rrweb | ||
| */ | ||
| export function getPrivacyOptions({ | ||
| mask, | ||
| unmask, | ||
| block, | ||
| unblock, | ||
| ignore, | ||
|
|
||
| // eslint-disable-next-line deprecation/deprecation | ||
| blockClass, | ||
| // eslint-disable-next-line deprecation/deprecation | ||
| blockSelector, | ||
| // eslint-disable-next-line deprecation/deprecation | ||
| maskTextClass, | ||
| // eslint-disable-next-line deprecation/deprecation | ||
| maskTextSelector, | ||
| // eslint-disable-next-line deprecation/deprecation | ||
| ignoreClass, | ||
| }: GetPrivacyOptions): GetPrivacyReturn { | ||
| const maskSelector = getOption(mask, ['.sentry-mask', '[data-sentry-mask]'], maskTextClass, maskTextSelector); | ||
| const unmaskSelector = getOption(unmask, ['.sentry-unmask', '[data-sentry-unmask]']); | ||
|
|
||
| const options: GetPrivacyReturn = { | ||
| // We are making the decision to make text and input selectors the same | ||
| maskTextSelector: maskSelector, | ||
| unmaskTextSelector: unmaskSelector, | ||
| maskInputSelector: maskSelector, | ||
| unmaskInputSelector: unmaskSelector, | ||
|
|
||
| blockSelector: getOption(block, ['.sentry-block', '[data-sentry-block]'], blockClass, blockSelector), | ||
| unblockSelector: getOption(unblock, ['.sentry-unblock', '[data-sentry-unblock]']), | ||
| ignoreSelector: getOption(ignore, ['.sentry-ignore', '[data-sentry-ignore]'], ignoreClass), | ||
| }; | ||
|
|
||
| if (blockClass instanceof RegExp) { | ||
| options.blockClass = blockClass; | ||
| } | ||
|
|
||
| if (maskTextClass instanceof RegExp) { | ||
| options.maskTextClass = maskTextClass; | ||
| } | ||
|
|
||
| return options; | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just to be clear (we should put this in the changelog), this means passing through "random" rrweb option is not possible anymore in this release!