From 98e5b684d13701aef42e07a6d22420bdbaad25a0 Mon Sep 17 00:00:00 2001 From: Jennarong Muengtaweepongsa Date: Mon, 13 Jul 2020 17:10:52 +0700 Subject: [PATCH 1/7] feat: Docs for new Redux integration in @sentry/react --- .../platforms/javascript/react.md | 132 ++++++++++++++++++ 1 file changed, 132 insertions(+) diff --git a/src/collections/_documentation/platforms/javascript/react.md b/src/collections/_documentation/platforms/javascript/react.md index 4aac0e1cce182..fbd5c18e23ac5 100644 --- a/src/collections/_documentation/platforms/javascript/react.md +++ b/src/collections/_documentation/platforms/javascript/react.md @@ -146,3 +146,135 @@ class App extends React.Component { export default App; ``` + +## Redux + +{% version_added 5.20.0 %} + +Redux support is included in the `@sentry/react` package since version `5.20.0`. To use redux you would use `Sentry.createReduxEnhancer` at the same place that you initialize your Redux store. + + +```js +import { createStore, compose } from 'redux'; +import * as Sentry from '@sentry/react' + +// ... + +const sentryReduxEnhancer = Sentry.createReduxEnhancer({ + // Optionally pass options listed below +}); + +const store = createStore(rootReducer, sentryReduxEnhancer); + +// ... + +``` + +If you have other enhancers or middleware such as `thunk` you would do: + +```js +const store = createStore(rootReducer, compose(applyMiddleware(thunk), sentryReduxEnhancer)); +``` + +{% capture __alert_content -%} +Sentry uses a redux **enhancer**, this means that you neither pass it to `applyMiddleware` nor call the method when you pass it to the `createStore` method, you would just pass it as indicated above. +{%- endcapture -%} +{%- include components/alert.html + title="Note" + content=__alert_content + level="info" +%} + +### Redux Enhancer Options + +Pass an options object as the first parameter to `Sentry.createReduxEnhancer` to configure it. + +{% capture __alert_content -%} +We advise against sending sensitive information to Sentry, but if you do, we will try our best to filter out things such as user passwords. +{%- endcapture -%} +{%- include components/alert.html + title="Note" + content=__alert_content + level="warning" +%} + +#### `actionTransformer` (Function) + +Used to remove sensitive information from actions. The first parameter passed to the function is the Redux action. Return `null` to not send the action to Sentry. By default we send all actions. + +```js +const sentryReduxEnhancer = Sentry.createReduxEnhancer({ + actionTransformer: action => { + if (action.type === "GOVERNMENT_SECRETS") { + // Return null to not log the action to Sentry + return null; + } + if (action.type === "SET_PASSWORD" ) { + // return a transformed action to remove sensitive information + return { + ...action, + password: null + } + }; + + return action; + } +}); +``` + +#### `stateTransformer` (Function) + +Used to remove sensitive information from state. The first parameter passed to the function is the Redux state. Return `null` to not attach the state to events sent to Sentry. Note that if you do choose to not send state to Sentry, your errors might not have the latest version of the state attached. By default we attach all state changes. + +```js +const sentryReduxEnhancer = Sentry.createReduxEnhancer({ + stateTransformer: state => { + if (state.topSecret.doNotSend) { + // Return null to not send this version of the state. + return null; + } + + // Transform the state to remove sensitive information + const transformedState = { + ...state, + topSecret: { + ...state.topSecret, + // Replace sensitive information with something else + nuclearLaunchCodes: "I love pizza", + // or just remove it entirely + hiddenTreasureLocation: null + }, + giganticState: null + }; + + return transformedState; + } +}) +``` + +### `actionBreadcrumbCategory` (string) + +Category of the breadcrumb sent by actions. Default is `"redux.action"`. + +### `actionBreadcrumbType` (string) + +Type of the breadcrumb sent by actions. Default is `info`. + +### `stateContextKey` (string) + +The context key to pass the state to. Default is `redux.state`. Note that if you change this, the context may not be displayed as nicely on the Sentry dashboard. + +### `configureScopeWithState` (Function) + +Called on every state update, configure the Sentry Scope with the redux state. The first parameter is the scope, which is the same scope instance that you would get when you call `Sentry.configureScope`, and the second parameter is the latest Redux state. + +```js +const sentryReduxEnhancer = Sentry.createReduxEnhancer({ + configureScopeWithState: (scope, state) => { + // Set tag if the user is using imperial units. + if (state.settings.useImperialUnits) { + scope.setTag('user.usesImperialUnits', true); + } + } +}); +``` \ No newline at end of file From 506bfa42c880f38236c657f29b32aec12fa3c8d5 Mon Sep 17 00:00:00 2001 From: Jenn Mueng <30991498+jennmueng@users.noreply.github.com> Date: Tue, 14 Jul 2020 14:37:09 +0700 Subject: [PATCH 2/7] ref: Apply suggestions from code review Co-authored-by: Tien "Mimi" Nguyen --- .../_documentation/platforms/javascript/react.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/collections/_documentation/platforms/javascript/react.md b/src/collections/_documentation/platforms/javascript/react.md index fbd5c18e23ac5..aacd3b7a3bc50 100644 --- a/src/collections/_documentation/platforms/javascript/react.md +++ b/src/collections/_documentation/platforms/javascript/react.md @@ -151,7 +151,7 @@ export default App; {% version_added 5.20.0 %} -Redux support is included in the `@sentry/react` package since version `5.20.0`. To use redux you would use `Sentry.createReduxEnhancer` at the same place that you initialize your Redux store. +Redux support is included in the `@sentry/react` package since version `5.20.0`. To apply Redux, use `Sentry.createReduxEnhancer` at the same place that you initialize your Redux store. ```js @@ -170,14 +170,14 @@ const store = createStore(rootReducer, sentryReduxEnhancer); ``` -If you have other enhancers or middleware such as `thunk` you would do: +If you have other enhancers or middleware such as `thunk`: ```js const store = createStore(rootReducer, compose(applyMiddleware(thunk), sentryReduxEnhancer)); ``` {% capture __alert_content -%} -Sentry uses a redux **enhancer**, this means that you neither pass it to `applyMiddleware` nor call the method when you pass it to the `createStore` method, you would just pass it as indicated above. +Sentry uses a redux **enhancer**. Pass the enhancer, as indicated above. Don't pass it to `applyMiddleware` and don't call the method when you pass it to the `createStore` method. {%- endcapture -%} {%- include components/alert.html title="Note" @@ -224,7 +224,7 @@ const sentryReduxEnhancer = Sentry.createReduxEnhancer({ #### `stateTransformer` (Function) -Used to remove sensitive information from state. The first parameter passed to the function is the Redux state. Return `null` to not attach the state to events sent to Sentry. Note that if you do choose to not send state to Sentry, your errors might not have the latest version of the state attached. By default we attach all state changes. +Used to remove sensitive information from state. The first parameter passed to the function is the Redux state. Return `null` to not attach the state to events sent to Sentry. Note that if you choose not to send state to Sentry, your errors might not have the latest version of the state attached. By default, we attach all state changes. ```js const sentryReduxEnhancer = Sentry.createReduxEnhancer({ @@ -266,7 +266,7 @@ The context key to pass the state to. Default is `redux.state`. Note that if you ### `configureScopeWithState` (Function) -Called on every state update, configure the Sentry Scope with the redux state. The first parameter is the scope, which is the same scope instance that you would get when you call `Sentry.configureScope`, and the second parameter is the latest Redux state. +Called on every state update, configure the Sentry Scope with the Redux state. The first parameter is the scope, which is the same scope instance that you would get when you call `Sentry.configureScope`, and the second parameter is the latest Redux state. ```js const sentryReduxEnhancer = Sentry.createReduxEnhancer({ @@ -277,4 +277,4 @@ const sentryReduxEnhancer = Sentry.createReduxEnhancer({ } } }); -``` \ No newline at end of file +``` From e99309200d6f08342912e1069965c1f161a80fdb Mon Sep 17 00:00:00 2001 From: Jennarong Muengtaweepongsa Date: Tue, 14 Jul 2020 14:51:06 +0700 Subject: [PATCH 3/7] ref: Remove docs on configurable keys --- .../_documentation/platforms/javascript/react.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/src/collections/_documentation/platforms/javascript/react.md b/src/collections/_documentation/platforms/javascript/react.md index aacd3b7a3bc50..dd91d0a693d98 100644 --- a/src/collections/_documentation/platforms/javascript/react.md +++ b/src/collections/_documentation/platforms/javascript/react.md @@ -252,18 +252,6 @@ const sentryReduxEnhancer = Sentry.createReduxEnhancer({ }) ``` -### `actionBreadcrumbCategory` (string) - -Category of the breadcrumb sent by actions. Default is `"redux.action"`. - -### `actionBreadcrumbType` (string) - -Type of the breadcrumb sent by actions. Default is `info`. - -### `stateContextKey` (string) - -The context key to pass the state to. Default is `redux.state`. Note that if you change this, the context may not be displayed as nicely on the Sentry dashboard. - ### `configureScopeWithState` (Function) Called on every state update, configure the Sentry Scope with the Redux state. The first parameter is the scope, which is the same scope instance that you would get when you call `Sentry.configureScope`, and the second parameter is the latest Redux state. From ef15fa6c4024d66218fcaf0c11d3caafa5db8d09 Mon Sep 17 00:00:00 2001 From: Jennarong Muengtaweepongsa Date: Tue, 14 Jul 2020 14:51:45 +0700 Subject: [PATCH 4/7] ref: "Apply Sentry to Redux" --- src/collections/_documentation/platforms/javascript/react.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/collections/_documentation/platforms/javascript/react.md b/src/collections/_documentation/platforms/javascript/react.md index dd91d0a693d98..313706b203411 100644 --- a/src/collections/_documentation/platforms/javascript/react.md +++ b/src/collections/_documentation/platforms/javascript/react.md @@ -151,7 +151,7 @@ export default App; {% version_added 5.20.0 %} -Redux support is included in the `@sentry/react` package since version `5.20.0`. To apply Redux, use `Sentry.createReduxEnhancer` at the same place that you initialize your Redux store. +Redux support is included in the `@sentry/react` package since version `5.20.0`. To apply Sentry to Redux, use `Sentry.createReduxEnhancer` at the same place that you initialize your Redux store. ```js From 16738711f4968b3adfb64a12aaaafc1e6a8438df Mon Sep 17 00:00:00 2001 From: Jennarong Muengtaweepongsa Date: Wed, 15 Jul 2020 15:31:43 +0700 Subject: [PATCH 5/7] feat: Add section on Normalization Depth --- .../_documentation/platforms/javascript/react.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/collections/_documentation/platforms/javascript/react.md b/src/collections/_documentation/platforms/javascript/react.md index 313706b203411..efb07e26db8fe 100644 --- a/src/collections/_documentation/platforms/javascript/react.md +++ b/src/collections/_documentation/platforms/javascript/react.md @@ -185,6 +185,16 @@ Sentry uses a redux **enhancer**. Pass the enhancer, as indicated above. Don't p level="info" %} +### Normalization Depth + +By default Sentry SDKs normalize any context to a depth of 3, which in the case of sending Redux state you probably will want to increase that. You do so by passing `normalizeDepth` to the `Sentry.init` call: +```js +Sentry.init({ + dsn: '___DSN___', + normalizeDepth: 10 // Or however deep you want your state context to be. +}) +``` + ### Redux Enhancer Options Pass an options object as the first parameter to `Sentry.createReduxEnhancer` to configure it. From 11a8cf9399472a6320a18e3afe547ec84f760b1f Mon Sep 17 00:00:00 2001 From: Jennarong Muengtaweepongsa Date: Wed, 15 Jul 2020 15:33:37 +0700 Subject: [PATCH 6/7] ref: Comments in code samples --- src/collections/_documentation/platforms/javascript/react.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/collections/_documentation/platforms/javascript/react.md b/src/collections/_documentation/platforms/javascript/react.md index efb07e26db8fe..42007c4924b96 100644 --- a/src/collections/_documentation/platforms/javascript/react.md +++ b/src/collections/_documentation/platforms/javascript/react.md @@ -220,7 +220,7 @@ const sentryReduxEnhancer = Sentry.createReduxEnhancer({ return null; } if (action.type === "SET_PASSWORD" ) { - // return a transformed action to remove sensitive information + // Return a transformed action to remove sensitive information return { ...action, password: null @@ -254,6 +254,7 @@ const sentryReduxEnhancer = Sentry.createReduxEnhancer({ // or just remove it entirely hiddenTreasureLocation: null }, + // You should also remove large data that is irrelevant to debugging to not clutter your Sentry issues giganticState: null }; From 2b1c940e8e50017ff4411e811cb2331f762bfbda Mon Sep 17 00:00:00 2001 From: Jenn Mueng <30991498+jennmueng@users.noreply.github.com> Date: Tue, 21 Jul 2020 18:33:26 +0700 Subject: [PATCH 7/7] ref: Add empty line above js example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Kamil Ogórek --- src/collections/_documentation/platforms/javascript/react.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/collections/_documentation/platforms/javascript/react.md b/src/collections/_documentation/platforms/javascript/react.md index 42007c4924b96..5f1c803737bd4 100644 --- a/src/collections/_documentation/platforms/javascript/react.md +++ b/src/collections/_documentation/platforms/javascript/react.md @@ -188,12 +188,12 @@ Sentry uses a redux **enhancer**. Pass the enhancer, as indicated above. Don't p ### Normalization Depth By default Sentry SDKs normalize any context to a depth of 3, which in the case of sending Redux state you probably will want to increase that. You do so by passing `normalizeDepth` to the `Sentry.init` call: + ```js Sentry.init({ dsn: '___DSN___', normalizeDepth: 10 // Or however deep you want your state context to be. }) -``` ### Redux Enhancer Options