feat: Explicit Scope for captureException and captureMessage

[kamilogorek]

This PR introduces a second, optional argument to captureException and captureMessage methods, that allows to provide some custom data directly to the scope.

Provided data will be merged with what's already on the scope, unless explicitly cleared using a callback method.

It works in three variations:

• plain object containing updatable attributes
• Scope instance that'll extract the attributes from
• callback function that'll receive the current scope as an argument and allow for modifications

List of allowed keys:

tags
extra
contexts
user
level
fingerprint

Example usages:

Sentry.captureException(new Error("wat"), {
  tags: {
    wat: "ok",
  }
});

Sentry.captureMessage("hey", {
  user: {
    id: 1337
  }
});

// Explicitly clear what has been already stored on the scope
Sentry.captureException(new Error("clean as never"), scope => {
  scope.clear();
  scope.setTag("clean", "slate");
  return scope;
});

// Use Scope instance to store the data (it'll still merge with the global scope)
const scope = new Sentry.Scope();
scope.setTag("idontknow", "whattodo");
Sentry.captureException(new Error("mkey"), scope);

// Use Scope instance to store the data and ignore global one completely
const scope = new Sentry.Scope();
scope.setTag("idontknow", "whattodo");
Sentry.captureException(new Error("mkey"), () => scope);

Ref: #1607
Notion: https://www.notion.so/sentry/Explicit-Scope-797e8b674010494d8854001281cf8769#8be8a9f0b4064842904d3e649bfac407
Asana: https://app.asana.com/0/1169125731075107/1175779896688409

[getsentry-bot]

	Messages
📖	@sentry/browser bundle gzip'ed minified size: (ES5: 16.9385 kB) (ES6: 15.9707 kB)
📖	✅ TSLint passed

Generated by 🚫 dangerJS against d019dbb

[HazAT]

While I really appreciate the PR description maybe let's add a few sentences about the motivation and link issues. Also, let's link the notion doc that will soon move to develop.sentry.dev

[HazAT]

Good PR, before merging, let's discuss in which version we want to release this.

[3zzy]

@HazAT @kamilogorek How does it differ from withScope? When should I use this compared to withScope? which is the preferred way?

[diegopamio]

When will be this one be released?

[kamilogorek]

@diegopamio already shipped in 5.16 :)

[3zzy]

@HazAT @kamilogorek How does it differ from withScope? When should I use this compared to withScope? which is the preferred way?

@kamilogorek @HazAT Could you please clarify the difference between withScope and this additional argument? Thanks!

[kamilogorek]

@3zzy there's effectively none for most of the cases. The only difference is that withScope gives you a direct access to the scope, so you can inspect it, or do things like scope.addEventProcessor for some one-off event mutation.

[3zzy]

@kamilogorek Thanks, but it doesn't seem to work when using a custom hub, for example:

var client1 = new Sentry.BrowserClient({ ... });
var hub1 = new Sentry.Hub(client1)
hub1.captureException(new Error("wat"), {
 user: {
    id: 1337
  },
  tags: {
    wat: "ok",
  }
});

The error is tracked in Sentry but no tag or user ID is visible.

[kamilogorek]

@3zzy hub has a different function definition, that's why it doesn't work like that. Explicit scopes are meant to make "common usecases" easier to execute.

Compare https://github.com/getsentry/sentry-javascript/blob/master/packages/minimal/src/index.ts#L24 to https://github.com/getsentry/sentry-javascript/blob/master/packages/hub/src/hub.ts#L157

If you want to use them in custom hubs, you need to tell the hub that what you pass to it is a captureContext.

var client1 = new Sentry.BrowserClient({ ... });
var hub1 = new Sentry.Hub(client1)
hub1.captureException(new Error("wat"), {
  captureContext: {
   user: {
      id: 1337
    },
    tags: {
      wat: "ok",
    }
  }
});