Tracking issue for @sentry/* SDKs

Next Generation SDK Discussion

As you might have noticed, we have started pushing out pre-release versions for our next line of JavaScript SDKs. You can identify them by the @sentry/* namespace on NPM. The goal in this new lineup is to provide a more convenient interface and improved consistency between various JavaScript environments.

The SDKs are developed in mono-repository located in packages.

Updated Interface

import { init, captureMessage } from '@sentry/browser';

init({
  dsn: '__DSN__',
  // ...
});

captureMessage('Hello, world!');

Library minimal

A new feature of this SDK lineup is the minimal package. It allows library authors add support for a Sentry SDK without having to bundle the entire SDK or being dependent on a specific platform. If the library is included and a Sentry SDK is present, it will automagically work:

import * as Sentry from '@sentry/minimal';

// Add a breadcrumb for future events
Sentry.addBreadcrumb({
  message: 'My Breadcrumb',
  // ...
});

// Capture exceptions, messages or manual events
Sentry.captureMessage('Hello, world!');
Sentry.captureException(new Error('Good bye'));
Sentry.captureEvent({
  message: 'Manual',
  stacktrace: [
    // ...
  ],
});

We hope to see library authors adopt this feature in the future to facilitate better error tracking across the ecosystem.

Scope concept

We introduced a new concept we called Scope. A Scope holds an isolated state of breadcrumbs, context and other metadata. raven-node and raven-js had a similar feature, ambiguously called “context”. There always is a “default” Scope which handles all the stuff as we did before you have to do nothing but we also support pushing new a Scope if you ever want to have isolated context information lets say for example, each request that comes in in a node application should have it’s own Scope.

To add extra, tags or user to your event you have to call:

import * as Sentry from '@sentry/browser';

// Set user information, as well as tags and further extras
Sentry.configureScope(scope => {
  scope.setExtra('battery', 0.7);
  scope.setTag('user_mode', 'admin');
  scope.setUser({ id: '4711' });
  // scope.clear();
});

Sentry.captureMessage("Hello World!"); // This event contains all scope information from the global scope

If you want to have isolated information for only on specific event you can to:

import * as Sentry from '@sentry/browser';

Sentry.getDefaultHub().withScope(() => {
   // We are here in an isolated new Scope, we inherited all the stuff from the parent 
   // but after this functions returns the Scope is popped and removed

  Sentry.configureScope(scope => {
    scope.setExtra('battery', 0.9); // We overwrite battery extra
  });

  Sentry.captureMessage("Hello World!"); // This will contain all scope info from before + battery is overwritten just for this message
});

[captbaritone]

Hey! I maintain raven-for-redux, and I’m starting to look at building a version of that library to support the new SDK. I’m looking forward to having an API that can work consistently for Node (server side rendering) React Native and the Browser. Previous incompatibility has been a source of confusion for my users.

I think the only thing I see missing is a way to lazily configure the scope. With raven-for-redux we let users attach their entire app state as context. Since the entire state may be too large, or may need to redacted in some way, we allow the user to specify a state transform function which we will run before the report is sent. This is too expensive to do on every state update, so previously we relied on Raven. setDataCallback to run the transform lazily (only when it was time to actually submit a message/error).

If you do support registering a callback like this, it would also be good to support unregistering the callback, since in a server side rendering context we may want to (lazily) set this scope once per request.

An API method like Sentry.configureScope, except lazy, could probably get the job done:

import createStore from 'redux';

const store = createStore(/* ... */);

const unsubscribe = Sentry.configureScopeOnError(scope => {
  scope.setExtra('state', transformState(store.getState()));
  scope.setUser(deriveUserFromState(store.getState()));
});

Another option would be to expose some way to register a generic onError callback which will be called before the scope data is collected. With this, we could build our own configureScopeOnError:

import createStore from 'redux';

const store = createStore(/* ... */);

const unsubscribe = Sentry.onError(()=> {
  Sentry.configureScope((scope) => {
    scope.setExtra('state', transformState(store.getState()));
    scope.setUser(deriveUserFromState(store.getState()));
  });
});

These are just the ideas the jump to mind immediately. Maybe you see another way to do it, or a clearer API?

[HazAT]

Update: It’s already in master and the next rc will contain it. We exposed withScope and added level on the scope, so the final code looks like this:

Sentry.withScope(scope => {
  scope.setTag(bla, 'blub').setLevel('warning');
  Sentry.captureException(new Error('bla'));
});

This example will have the tag and level only set for this exception. If you want to set something globally, you still need to use configureScope.