Tracking issue for @sentry/* SDKs

[jan-auer]

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
});

[HazAT]

https://github.com/getsentry/sentry-cordova and https://github.com/getsentry/sentry-electron are both using our new SDKs internally. We already got a lot of feedback and the public API and in general should be pretty safe now.

[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]

@captbaritone Thank you for taking the time to look at our new SDK.
I hope that I understood the question correctly if so I think I will have a good solution for this.

For the new SDKs we came up with something we call integrations.
An Integration basically can be anything that hooks into the flow of the client sending an event, even emitting event.

So I think what you want to do is build an integration.
See this integration for example: https://github.com/getsentry/sentry-javascript/blob/master/packages/browser/src/integrations/sdkinformation.ts

We introduced eventProcessor which is basically a "stackable" dataCallback.
They will be executed in the order in which they where installed.

so you could do something like this:

public install(): void {
    getCurrentHub().addEventProcessor(async (event: SentryEvent) => {
        // mutate event before sending in here
        // return mutated event OR null of you want to discard it
    });
}

This integration (in node) also configures a scope:
https://github.com/getsentry/sentry-javascript/blob/master/packages/node/src/integrations/onunhandledrejection.ts

And the usage of you integration would also be super easy:

import * as Sentry from '@sentry/browser';
import { ReduxIntegration } from "raven-for-redux";

init({
  dsn: '__DSN__',
  integrations: (integrations) => {
     // integrations include all default integrations we provide
     // you could do this:
     integrations.push(new ReduxIntegration(/* you can pass anything here e.g. store*/));
     return integrations;
  }
});

I hope you get the idea, integrations are very powerful and make our SDKs super extensible in a logical understandable way.
Please let me know if this helps.

[kamilogorek]

We. Are. Doneee.

[SimonSchick]

Hey, I'm not sure if this is the right place to ask but I'm currently playing with the new SDK and have some questions:

1: How do we set a custom log level when logging exceptions via .captureException? Previously this was possible and sometimes we log errors as warning if it's not a critical issue, this seems to be no longer possible, perhaps allow us to set the log level on scope?

2: How exactly does scope work, the docs are not clear on this at all?

I assume this:

Sentry.configureScope(scope => {
  scope.setUser({ id: 'superuser' });
  Sentry.captureException(err);
});

2.1: Do I need to need to explictly call scope.clear() to avoid the configuration to leak into other captured events?
2.1.1: If scope settings persist, how do I define global scope settings?
2.2: Is configureScope called synchronously?

[SimonSchick]

Furthermore, how we do we set global tags now?