New JavaScript SDKs - Feedback wanted

[HazAT]

< back to posts

Javascript Forum

As already announced in the Blog Post we were working on rewriting our SDKs to streamline the experience across different environments.
You can find an overview of the SDKs in the readme here: GitHub - getsentry/sentry-javascript: Official Sentry SDKs for JavaScript

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.

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

ref: Tracking issue for @sentry/* SDKs · Issue #1281 · getsentry/sentry-javascript · GitHub

[dcherman]

@HazAT Where I work, I maintain a library that composes raven-node in order to extract common information from the environment which includes parsing the user from an express request if/when an error occurs, promoting some headers to tags for filtering, and ignoring some errors based on what environment you’re in.

Previously, I was accomplishing all of this pretty easily with a combination of parseUser, dataCallback, and beforeSendCallback.

It looks like I could accomplish most/all of this using the beforeSend callback in the new SDKs, but it feels like the correct approach would be to use an integration.

There’s very little documentation about creating custom integrations, but based on the ones in the @sentry/node package, it seems like using addGlobalEventProcessor from the current hub is the way to go, but it’s not exported from @sentry/node. Is that a bug/oversight, or is there a different way to accomplish what I’m trying to do that’s already publicly exposed?

[HazAT]

Thanks for your feedback on this matter, you are right, writing your own Integration would be the cleanest way to handle this.
I agree that our docs about writing your own integration can be improved by a lot (not many people asked for this yet).

That we did not expose addGlobalEventProcessor is a mistake on our part, we recently introduced this with 4.2.0, we will fix that in the next update.
(Release should come this week)

[HazAT]

4.2.4 has been released exposing addGlobalEventProcessor

[andrewharvey]

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

For me the biggest frustration is I can’t find the API documentation which explains these. Can I pass an Object to capture message, or does it only accept a string?

For captureEvent can it be any object, or must I have an Object with message and stacktrace?

[HazAT]

Sorry for the late reply.
captureMessage only accepts a string, since it’s JS and we don’t run stuff users pass in against a schema before sending it off to the Server, you could pass anything but it could be that either the event will be discarded or sanitized by the server.

captureEvent accepts an object SentryEvent properties can be found here http://getsentry.github.io/sentry-javascript/interfaces/types.sentryevent.html
or here https://docs.sentry.io/development/sdk-dev/attributes/

[cassey]

I came here because I was confused about where the SDK documentation lives, too.

I want to know what arguments captureMessage takes. So I made a web search for ‘captureMessage Sentry’ and landed on this page: Usage for Node.js | Sentry Documentation.

This page tells me it’s out of date, so I clicked the link to go to the new documentation:

and then made my way to the page for manually capturing a message. https://docs.sentry.io/error-reporting/capturing/?platform=node

At the bottom, I see this text:

Capturing Events
SDKs generally also provide ways to capture entire custom event objects. This is what integrations internally use to capture bespoke events with a lot of extra data fed into. For more information about that consult the API documentation of the SDK.

Except, I don’t know where to go to find the API documentation of the Javascript SDK. I thought that’s where I was already, in fact.

Where should I look to find the exact call signatures accepted by the Sentry Javascript SDK?

[HazAT]

Hey,

Sorry for this we are working to make the docs more explicit and clear.
We also have a typedoc ref: http://getsentry.github.io/sentry-javascript/modules/minimal.html#capturemessage

This is the signature of captureMessage, all calls of Sentry.* go through the minimal package.

[cassey]

Thanks, that’s helpful!