Repository files navigation

.

Sentry now recommends using their new SDK@sentry/browser rather than Raven. Check outredux-sentry-middleware for an API compatible fork of this library that supports the new SDK!

Note: Requires Raven >= 3.9.0. Raven 3.14.0 hasa bugwhich this library triggers

Logs the type of each dispatched action to Raven as "breadcrumbs" and attachesyour last action and current Redux state as additional context.

Inspired byredux-raven-middleware but with a slightlydifferent approach.

npm install --save raven-for-redux

// store.jsimportRavenfrom"raven-js";// Or, you might already have this as `window.Raven`.import{createStore,applyMiddleware}from"redux";importcreateRavenMiddlewarefrom"raven-for-redux";import{reducer}from"./my_reducer";Raven.config("<YOUR_DSN>").install();exportdefaultcreateStore(reducer,applyMiddleware(// Middlewares, like `redux-thunk` that intercept or emit actions should// precede `raven-for-redux`.createRavenMiddleware(Raven,{// Optionally pass some options here.})));

For a working example, see theexample directory.

raven-for-redux has TypeScript bindings available throughDefinitelyTyped. Please note the import style below, as it differs from the JavaScript example and is required for these typings.

import*asRavenfrom"raven-js";import*ascreateRavenMiddlewarefrom"raven-for-redux";import{applyMiddleware,createStore}from"redux";//... (same as JavaScript example, but now with proper typings)

This library makes, what I think are, a few improvements overredux-raven-middlware:

1. Raven is injected rather than being setup inside the middleware. This allowsfor more advanced configuration of Raven, as well as cases where Raven hasalready been initialized. For example, if you include Raven as its own<script> tag.
2. Adds your state and last action as context toall errors, not just reducerexceptions.
3. Allows filtering action breadcrumbs before sending to Sentry
4. Allows you to define a user context mapping from the state

• Raven(Raven Object): A configured and "installed"Raven object.
• [options](Object): See below for detailed documentation.

While the default configuration should work for most use cases, Raven for Reduxcan be configured by providing an options object with any of the followingoptional keys.

Default:action => action.type

breadcrumbMessageFromAction allows you to specify a transform function which is passed theaction object and returns astring that will be used as the message of the breadcrumb.

By defaultbreadcrumbMessageFromAction returnsaction.type.

Finally, be careful not to mutate youraction within this function.

See the SentryBreadcrumb documentation.

Default:action => undefined

Raven allows you to attach additional context information to each breadcrumbin the form of adata object.breadcrumbDataFromAction allows you to specifya transform function which is passed theaction object and returns adataobject. Which will be logged to Sentry along with the breadcrumb.

Ideally we could log the entire content of each action. If we could, wecould perfectly replay the user's entire session to see what went wrong.

However, the default implementation of this function returnsundefined, which meansno data is attached. This is because there area few gotchas:

• The data object must be "flat". In other words, each value of the object must be a string. The values may not be arrays or other objects.
• Sentry limits the total size of your error report. If you send too much data,the error will not be recorded. If you are going to attach data to yourbreadcrumbs, be sure you understand the way it will affect the total sizeof your report.

Finally, be careful not to mutate youraction within this function.

See the SentryBreadcrumb documentation.

Default:action => action

In some cases your actions may be extremely large, or contain sensitive data.In those cases, you may want to transform your action before sending it toSentry. This function allows you to do so. It is passed the last dispatchedaction object, and should return a serializable value.

Be careful not to mutate youraction within this function.

If you have specified adataCallback when you configured Raven, note thatactionTransformer will be appliedbefore your specifieddataCallback.

Default:state => state

In some cases your state may be extremely large, or contain sensitive data.In those cases, you may want to transform your state before sending it toSentry. This function allows you to do so. It is passed the current stateobject, and should return a serializable value.

Be careful not to mutate yourstate within this function.

If you have specified adataCallback when you configured Raven, note thatstateTransformer will be appliedbefore your specifieddataCallback.

Default:"redux-action"

Each breadcrumb is assigned a category. By default all action breadcrumbs aregiven the category"redux-action". If you would prefer a different categoryname, specify it here.

Default:action => true

If your app has certain actions that you do not want to send to Sentry, passa filter function in this option. If the filter returns a truthy value, theaction will be added as a breadcrumb, otherwise the action will be ignored.Note: even when the action has been filtered out, it may still be sent toSentry as part of the extra data, if it was the last action before an error.

This option was introduced in version 1.1.1.

Signature:state => userContext

Raven allows you to associcate auser context with each error report.getUserContext allows you to define a mapping from your Reduxstate tothe user context. WhengetUserContext is specified, the result ofgetUserContext will be used to derive the user context before sending anerror report. Be careful not to mutate yourstate within this function.

If you have specified adataCallback when you configured Raven, note thatgetUserContext will be appliedbefore your specifieddataCallback.When agetUserContext function is given, it will override any previouslyset user context.

This option was introduced in version 1.2.0.

Signature:state => tags

Raven allows you to associatetags with each report.getTags allows you to define a mapping from your Reduxstate toan object of tags (key → value). Be careful not to mutate yourstatewithin this function.

This option was introduced in version 1.3.1.

• AddbreadcrumbMessageFromAction method. (#98)

• AddgetTags option. (#69)

• The Raven "extras" that we add are merged with existing extras rather than replacing them. (#59)

• AddgetUserContext option. (#49)

• AddfilterBreadcrumbActions option. (#39)

• No changes. Just bringing the project out of beta.

• Refactor: Use implicit binding to track the state/last action. (1def9a7)

• Return the next middleware's (or the actualdispatch function's) return value. (#11)

• actionTransformer andstateTransformer are only run when reporting an error, rather than on every action. (#8)