NativeScript Sentry TraceWriter

This plugin provides a custom NativeScript TraceWriter that will log messages to Sentry.io using the Official Sentry SDK for Browsers. This is useful for capturing trace messages in production from user iOS and Android devices. This plugin is based on Todd Anglin's NativeScript Raven TraceWriter (https://github.com/toddanglin/nativescript-trace-raven) plugin which uses the depreacted (but supported) Raven.JS library for Sentry.

Getting started

To add the plug-in to a NativeScript project:

tns plugin add nativescript-trace-sentry

NOTE: To use this plug-in, a "DSN" key from Sentry.io is required. This key is used to initialize the plug-in and send logs to a specific Sentry.io project.

Usage

Once the plug-in is installed, simply initialize the new TraceWriter. This can be done in different ways, but for easy global usage, setup the new TraceWriter when then app starts:

app.ts

import * as app from 'application';
import * as trace from 'trace';
import { TraceSentry } from 'nativescript-trace-Sentry';

app.on(app.launchEvent, (args: app.ApplicationEventData) => {
    let sentryDsn = "[YOUR SENTRY DSN KEY]";

    trace.setCategories(trace.categories.concat(trace.categories.Error, trace.categories.Debug));
    trace.addWriter(new TraceSentry(sentryDsn));
    trace.enable();
});

Then, in your app, just use trace as normal. The output will now be sent to Sentry.io.

Example:

trace.write("Something happened in the app", trace.categories.Error, trace.messageType.error);

NOTE: Sentry.io charges by log volume, so as a best practice, do not enable this custom TraceWriter during regular development

In addition to the trace message, this plug-in will send these additional details to Sentry with each log:

• NativeScript runtime version
• Device Platform (iOS/Android)
• Device OS Version
• Device Type (phone/tablet/etc)
• Device Model (iPhone, Galaxy S3, etc)
• Device Language (en-US, etc)
• Device UUID
• Device Orientation (portrait, landscape)
• Battery level (0 - 100, if available)
• App version name
• Environment name (default "Debug")
• User IP Address

Log level

Sentry.io provides three levels for classifying logs: info, warning and error.

When logging using the TraceWriter and trace API, the trace.messageType is mapped to Sentry log levels:

• trace.messageType.log === Log type: info
• trace.messageType.info === Log type: info
• trace.messageType.warn === Log type: warning
• trace.messageType.error === Log type: error

If trace.messageType is omitted, the default log level is error.

Extended use

When initializing Sentry, you can optionally provide an environment string to describe where the app is running when sending log messages. By default, this string is set to debug. If you want to specify your own environment string, just add it when initializing with your DSN key:

trace.addWriter(new TraceSentry(sentryDsn, "production"));

Logging Exceptions

Unlike using trace to record an Error, the Sentry.captureException API will also attempt to include Stack Trace information with the log.

import Sentry = require("Sentry-js");

try { 
  throw new Error("This is an example error with stack trace");
} catch (err) {
  Sentry.captureException(err);
}

Adding Breadcrumbs

You can manually create "breadcrumbs" that will be included with Sentry logs. Breadcrumbs are intended to show the path of actions that lead to an exception, app crash or log message. For example, to add a crumb when a button is tapped:

public buttonTap(args: EventData) {
  let btn = <Button>args.object;
  Sentry.addBreadcrumb({
    message: `Button tapped`,
    category: "action",
    data: {
      id: btn.id,
      text: btn.text
    },
    level: Sentry.Severity.Info
  });
}

Last EventId

The EventId is a globally unique string generated by Sentry for all logs. Sentry provides the ability to get the EventId for the most recent log so that you can present it to users and use for customer service reports. To get the most recent EventId with Sentry:

let eventId = Sentry.lastEventId();

Considerations

Sentry.io provides a generous free tier for logging events, but does eventually charge by logging volume. As a result, be careful to log only events that are helpful for troubleshooting in production.

That means: do not use trace.categories.All when logging to Sentry

This verbose logging will likely generate far more logs than needed, and quickly run-up your Sentry.io bill.

Best practices:

1. Only log to Sentry in production
2. Minimize the trace categories logged (minimum: trace.categories.Error)

Native Errors

Since this plug-in is running in the NativeScript JavaScript layer, it may not capture all native iOS or Android errors. This is generally okay as errors that relate to app code will be caught, but if native iOS/Android logging is needed, use a different plug-in like Firebase.

Auto Breadcrumbs

In addition to providing the custom TraceWriter, this plugin will automatically wire-up automatic breadcrumbs for these global Page events:

• onNavigatedTo
• onLoaded
• onShownModally

Whenever one of these events occurs, a new breadcrumb will get added to the history. To disable this behavior, initialize TraceSentry with an additional parameter:

new TraceSentry("[YOUR DSN KEY]", "production", false)

The last parameter will enable/disable auto-breadcrumbs created by this plug-in. Default is true (enabled).

Using the Demo

To try the demo for this plug-in, simply follow these steps:

1. Get a DSN key from Sentry.io
2. Clone this repo
3. Navigate to the demo folder and open app.ts in your code editor
4. Replace the sentryDsn string with your DSN key
5. Navigate back to the root of the cloned repo
6. Run npm run demo.ios or npm run demo.android

If the DSN key is not added before running the demo, the app will crash on launch.

Contributing

Want to help make this plug-in better? Report issues in GitHub:

https://github.com/timdoege/nativescript-trace-sentry/issues

Pull requests welcome.