Skip to content

Sentry🔗

Setup a Sentry integration for Javascript.

Installation🔗

See the official installation guide

Configuration🔗

Get your Sentry DSN from Settings > Projects > Your project > Client Keys (DSN). You will also need to define the environment, the project name and optionally a release version.

Use .env files to set these variables for your different environments:

1
2
3
4
5
SENTRY_DSN=https://your_sentry_key@sentry.io/1234
SENTRY_ORG=your_project_org
SENTRY_PROJECT=your_project_name
APP_RUNTIME_ENV=production
APP_VERSION=1.0

Alternatively, you can configure the Sentry project related info in a sentry.properties file:

1
2
3
defaults.url=https://sentry.io/
defaults.org=your_project_org
defaults.project=your_project_name

Info

The APP_RUNTIME_ENV comes from the Symfony convention for identifying the target / deploy environment (we also call this a tier in Manala).

If you use a VERSION file to store the app version number, you can use the following code to get it:

1
2
// webpack.config.js
const APP_VERSION = require('fs').readFileSync('./VERSION', 'utf8').trim();

Then use the APP_VERSION variable instead of process.env.APP_VERSION in the next code samples.

Note

If you don't bump the release version number in your project, you may want to set at least a different release name for production and staging releases. You can use the target environment name for that (ie: 1.0 and 1.0-staging or production and staging). While not mandatory, it'll allow you to have a clear separation between these environments and their generated artefacts.

Create a Sentry configuration module:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// assets/js/sentry.js
import * as Sentry from '@sentry/browser'

export default {
  /**
   * @see https://docs.sentry.io/error-reporting/configuration/?platform=browser
   * @see https://docs.sentry.io/enriching-error-data/context/?platform=browser
   */
  configure(app) {
    if (null === process.env.SENTRY_DSN) {
      return
    }

    Sentry.init({
      dsn: AppConfig.SENTRY_DSN,
      release: AppConfig.SENTRY_PROJECT + '@' + AppConfig.APP_VERSION,
      environment: AppConfig.APP_RUNTIME_ENV,
    })

    Sentry.configureScope(scope => {
      scope.setTag('project', AppConfig.SENTRY_PROJECT)
      scope.setTag('app', app)
      scope.setTag('node_env', AppConfig.NODE_ENV)
    })
  },

  setUser(id, email) {
    if (null === process.env.SENTRY_DSN) {
      return
    }

    Sentry.configureScope(scope => {
      scope.setUser({ id, email })
    })
  },
}

Note

The release value must be unique accross your Sentry organization. The convention is project_name@version.
See official documentation.

Tip

In order to use the env vars inside this runtime code snippet, you need to forward the env vars at build time, from your webpack.config.js file using the DefinePlugin Plugin and declaring each of the variables to forward explicitly in a AppConfig object.
Consult the dotenv cookbook to see how to do this.

Then, in your main javascript app file:

1
2
3
4
5
6
7
8
// assets/app.js

import Sentry from './js/sentry'
Sentry.configure('your_app_name') // E.g: front-office, admin, ...

// ...

Sentry.setUser(user.id, user.email)

Vue.js🔗

To use Sentry with your Vue application, add the following integration to your Sentry configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// assets/js/sentry.js
import Vue from 'vue'
import * as Sentry from '@sentry/browser'
import * as Integrations from '@sentry/integrations'

// ...

Sentry.init({
  // ...
  integrations: [
    /** @see https://docs.sentry.io/platforms/javascript/vue/ */
    new Integrations.Vue({ Vue, attachProps: true })
  ],
  // ...
})

// ...

Send source maps to Sentry🔗

To allow Sentry to indicate you the line in error in your not compiled/transpiled source code, you can ask Webpack to send your source maps to Sentry.

Use the Sentry for tools & CI special auth token on and put it in production and staging .env file.

Warning

This token is meant to be secret, and should therefore not be committed to your repository if it's likely to be opened somehow.
The Onisep project is such a case.

Add the following env var:

1
SENTRY_AUTH_TOKEN=

Install Sentry Webpack plugin:

1
yarn add @sentry/webpack-plugin --dev

Configure sur plugin in the Webpack config:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// webpack.config.js

Encore
  // ...
  .enableSourceMaps(true) // generate source maps even in production to be able to send them to sentry
  // ...
;

var webpackConfig = Encore.getWebpackConfig();

// If the SENTRY_AUTH_TOKEN is provided, register the sentry plugin to publish release automatically
if (process.env.SENTRY_AUTH_TOKEN) {
  /** @see https://github.com/getsentry/sentry-webpack-plugin */
  const SentryCliPlugin = require('@sentry/webpack-plugin');
  webpackConfig.plugins.push(new SentryCliPlugin({
    release: process.env.SENTRY_PROJECT + '@' + process.env.APP_VERSION,
    urlPrefix: '~/build',
    include: 'public/build/',
  }));
}

module.exports = webpackConfig;

Note

The release must be the same as in Sentry configuration.

Alternatively, you can also consult how this is made in the Onisep project.

Projects references🔗

Last update: December 20, 2024