From 42e2e08bbe1eea62aaa916b0016fcaf3281a4b2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Og=C3=B3rek?= Date: Wed, 29 Nov 2017 12:12:42 +0100 Subject: [PATCH] docs: Include Source Maps docs --- docs/index.rst | 10 ++++ docs/sourcemaps.rst | 125 ++++++++++++++++++++++++++++++++++++++++++++ docs/usage.rst | 9 ++++ 3 files changed, 144 insertions(+) create mode 100644 docs/sourcemaps.rst diff --git a/docs/index.rst b/docs/index.rst index 09f9a77..97c6f19 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -118,6 +118,15 @@ Raven can be configured to automatically capture breadcrubs for certain events i For more information, see :ref:`raven-recording-breadcrumbs`. +Dealing with Minified Source Code +--------------------------------- + +Raven and Sentry support `Source Maps +`_. If +you provide source maps in addition to your minified files that data +becomes available in Sentry. For more information see +:ref:`raven-node-sourcemaps`. + Middleware and Integrations --------------------------- @@ -137,6 +146,7 @@ is additional documentation available that covers all the rest: config usage integrations/index + sourcemaps coffeescript Resources: diff --git a/docs/sourcemaps.rst b/docs/sourcemaps.rst new file mode 100644 index 0000000..6b4b1af --- /dev/null +++ b/docs/sourcemaps.rst @@ -0,0 +1,125 @@ +.. _raven-node-sourcemaps: + +Source Maps +=========== + +Sentry supports un-minifying JavaScript via `Source Maps +`_. This lets you +view source code context obtained from stack traces in their original untransformed form, which is particularly useful for debugging minified code (e.g. UglifyJS), or transpiled code from a higher-level +language (e.g. TypeScript, ES6). + +Generating a Source Map +----------------------- + +Most modern JavaScript transpilers support source maps. Below are instructions for some common tools. + +Webpack +~~~~~~~ + +Webpack is a powerful build tool that resolves and bundles your JavaScript modules into files fit for running in the +browser. It also supports many different "loaders" which can convert higher-level languages like TypeScript and +ES6/ES2015 into browser-compatible JavaScript. + +Webpack can be configured to output source maps by editing ``webpack.config.js``. + +:: + + module.exports = { + // ... other config above ... + target: 'node', + devtool: 'source-map', + entry: { + "app": 'src/app.js' + }, + output: { + path: path.join(__dirname, 'dist'), + filename: '[name].js' + } + }; + + +Making Source Maps Available to Sentry +-------------------------------------- + +Source maps for Node.js projects should be uploaded directly to Sentry. + +Uploading Source Maps to Sentry +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sentry provides an abstraction called **Releases** which you can attach source artifacts to. +The release API is intended to allow you to store source files (and sourcemaps) within Sentry. + +It can be easily done with a help of the ``sentry-webpack-plugin``, which internally uses our Sentry CLI. + +* Start by creating a new authentication token under **[Account] > API**. +* Ensure you you have ``project:write`` selected under scopes. +* Install ``@sentry/webpack-plugin`` using ``npm`` +* Create ``.sentryclirc`` file with necessary config (see Sentry Webpack Plugin docs below) +* Update your ``webpack.config.json`` + +:: + + const SentryPlugin = require('@sentry/webpack-plugin'); + + module.exports = { + // ... other config above ... + plugins: [ + new SentryPlugin({ + release: process.env.RELEASE, + include: './dist', + ignore: ['node_modules', 'webpack.config.js'], + }) + ] + }; + + +You can take a look at `Sentry Webpack Plugin documentation `_ +for more information on how to configure the plugin. + +Additionally, you'll need to configure the client to send the ``release``: + +.. code-block:: javascript + + Raven.config('your-dsn', { + release: process.env.RELEASE + }); + +Note: You dont *have* to use `RELEASE` environment variables. You can provide them in any way you want. + +Additional information can be found in the `Releases API documentation +`_. + + +Updating Raven configuration to support Source Maps +--------------------------------------------------- + +In order for Sentry to understand how to resolve errors sources, we need to modify the data we send. +Because Source Maps support is still in experimental phase, this task is not integrated into the core library itself. +To do that however, we can normalize all urls using ``dataCallback`` method: + +.. code-block:: javascript + + var path = require('path'); + + Raven.config('your-dsn', { + // the rest of configuration + dataCallback: function (data) { + var stacktrace = data.exception && data.exception[0].stacktrace; + + if (stacktrace && stacktrace.frames) { + stacktrace.frames.forEach(function(frame) { + if (frame.filename.startsWith('/')) { + frame.filename = 'app:///' + path.basename(frame.filename); + } + }); + } + + if (data.culprit) { + data.culprit = normalizeUrl(data.culprit); + } + + return data; + } + } + ).install(); + diff --git a/docs/usage.rst b/docs/usage.rst index 10027db..cc79a34 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -381,3 +381,12 @@ Additional instances can be created like this: .. code-block:: javascript var Raven2 = new Raven.Client(); + + +Dealing with Minified Source Code +--------------------------------- + +Raven and Sentry support `Source Maps +`_. + +We have provided some instructions to creating Source Maps over at :ref:`raven-node-sourcemaps`.