Backtrace NestJS SDK

Backtrace captures and reports handled and unhandled exceptions in your production software so you can manage application quality through the complete product lifecycle.

The @backtrace/nestjs SDK connects your JavaScript application to Backtrace. The basic integration is quick and easy, after which you can explore the rich set of Backtrace features.

Table of Contents

1. Basic Integration - Reporting your first errors
   • Install the package
   • Integrate the SDK
   • Upload source maps
   • Add a Backtrace error interceptor
   • Add a Backtrace exception filter
   • Use the Backtrace exception handler in your code
2. Error Reporting Features
   • Attributes
   • File Attachments
   • Breadcrumbs
   • Application Stability Metrics
     • Metrics Configuration
     • Metrics Usage
   • Offline Database support
     • Database Configuration
     • Native crash support
     • Manual database operations
3. Advanced SDK Features
   • BacktraceClient options
   • Manually send an error
   • Modify/skip error reports
   • SDK Method Overrides

Basic Integration

Install the package

$ npm install @backtrace/nestjs

Integrate the SDK

Add the following code to your application before all other scripts to report NestJS errors to Backtrace.

// Import the BacktraceClient from @backtrace/nestjs
import { BacktraceClient, BacktraceConfiguration, BacktraceModule } from '@backtrace/nestjs';

// Configure client options
const options: BacktraceConfiguration = {
    // Submission url
    // <universe> is the subdomain of your Backtrace instance (<universe>.backtrace.io)
    // <token> can be found in Project Settings/Submission tokens
    url: 'https://submit.backtrace.io/<universe>/<token>/json',
};

// Initialize the client with the options
BacktraceClient.initialize(options);

// By default, Backtrace will send an error for Uncaught Exceptions and Unhandled Promise Rejections
// For capturing NestJS errors, see "Add a Backtrace error interceptor" in this README

// Register BacktraceModule in your base module
@Module({
    imports: [BacktraceModule],
    controllers: [AppController],
})
class AppModule {}

@Controller()
class AppController {
    // Inject BacktraceClient into your services or controllers
    constructor(private readonly _client: BacktraceClient) {}

    @Post()
    public endpoint() {
        // Manually send an error
        this._client.send(new Error('Something broke!'));
    }
}

Configuring the module

By default, the exception handler will exclude:

• all HttpException errors that have status < 500.

To include or exclude specific error types, pass options to BacktraceModule:

@Module({
    imports: [
        BacktraceModule.register({
            options: {
                includeExceptionTypes: [MyException],
                excludeExceptionTypes: (error) => error instanceof HttpException && error.getStatus() < 500,
            },
        }),
    ],
    controllers: [AppController],
})
class AppModule {}

As shown in the example above, includeExceptionTypes and excludeExceptionTypes accept either an array of error types, or a function that can return a boolean. The array types will match using instanceof. The function will have the thrown error passed as the first parameter.

Note: include is tested before exclude, so if exception type is both included and excluded, it will be included.

Upload source maps

Client-side error reports are based on minified code. Upload source maps and source code to resolve minified code to your original source identifiers.

(Source Map feature documentation)

Add a Backtrace error interceptor

While processing requests, NestJS will handle all exceptions thrown by controllers using the exception filters. This means that the exceptions will not be unhandled, and thus not captured by Backtrace. To capture these errors, you can use the BacktraceInterceptor class.

To add the interceptor globally, you can register it as APP_INTERCEPTOR:

import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { BacktraceModule, BacktraceInterceptor } from '@backtrace/nestjs';

@Module({
    imports: [BacktraceModule],
    providers: [
        {
            provide: APP_INTERCEPTOR,
            useExisting: BacktraceInterceptor,
        },
    ],
    controllers: [CatsController],
})
export class AppModule {}

Or, use app.useGlobalInterceptors:

const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new BacktraceInterceptor());

To use it on a specific controller, use UseInterceptors decorator:

@UseInterceptors(BacktraceInterceptor)
export class CatsController {}

or

@UseInterceptors(new BacktraceInterceptor({ ... }))
export class CatsController {}

For more information, consult NestJS documentation.

Configuring the interceptor

By default, the interceptor will use options from BacktraceModule. You can pass the options also directly to the interceptor:

new BacktraceInterceptor({
    includeExceptionTypes: [MyException],
    excludeExceptionTypes: (error) => error instanceof HttpException && error.getStatus() < 500,
});

Add a Backtrace exception filter

The interceptor does not capture all exceptions. For example, exceptions thrown by guards will not be captured by the interceptor. You can use the BacktraceExceptionFilter exception filter class. The filter will capture everything that the interceptor would capture.

To add the filter globally, you can register it as APP_FILTER:

import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { BacktraceModule, BacktraceExceptionFilter } from '@backtrace/nestjs';

@Module({
    imports: [BacktraceModule],
    providers: [
        {
            provide: APP_INTERCEPTOR,
            useExisting: BacktraceExceptionFilter,
        },
    ],
    controllers: [CatsController],
})
export class AppModule {}

Or, use app.useGlobalFilters:

const app = await NestFactory.create(AppModule);

// Note that you need to pass httpAdapter to BacktraceExceptionFilter as a second argument
const { httpAdapter } = app.get(HttpAdapterHost);
app.useGlobalInterceptors(new BacktraceExceptionFilter({}, httpAdapter));

To use it on a specific controller, use UseFilters decorator:

@UseFilters(BacktraceExceptionFilter)
export class CatsController {}

For more information, consult NestJS documentation.

Configuring the filter

By default, the filter will use options from BacktraceModule. You can pass the options also directly to the filter:

new BacktraceExceptionFilter({
    includeExceptionTypes: [MyException],
    excludeExceptionTypes: (error) => error instanceof HttpException && error.getStatus() < 500,
});

Use the Backtrace exception handler in your code

If you want to leverage the exception filtering and handling in your custom logic, e.g. exception filters, you can inject BacktraceExceptionHandler to your logic:

class MyExceptionFilter implements ExceptionFilter {
    constructor(private readonly handler: BacktraceExceptionHandler) {}

    catch(exception: unknown, host: ArgumentsHost) {
        const wasExceptionSent = this.handler.handleException(exception, host);
    }
}

Configuring the handler

By default, the handler will use options from BacktraceModule. You can pass the options also directly to the handler:

new BacktraceExceptionHandler({
    includeExceptionTypes: [MyException],
    excludeExceptionTypes: (error) => error instanceof HttpException && error.getStatus() < 500,
});

Error Reporting Features

Attributes

Custom attributes are key-value pairs that can be added to your error reports. They are used in report aggregation, sorting and filtering, can provide better contextual data for an error, and much more. They are foundational to many of the advanced Backtrace features detailed in Error Reporting documentation. By default attributes such as application name and version are populated automatically based on your package.json information. If Backtrace cannot find them, you need to provide them manually via userAttributes attributes.

There are several places where attributes can be added, modified or deleted.

Attach attributes object to BacktraceClient

It is possible to include an attributes object during BacktraceClient initialization. This list of attributes will be included with every error report, referred to as global attributes.

// Create an attributes object that can be modified throughout runtime
const attributes: Record<string, unknown> = {
    release: 'PROD',
};

// BacktraceClientOptions
const options: BacktraceConfiguration = {
    url: 'https://submit.backtrace.io/<universe>/<token>/json',

    // Attach the attributes object
    userAttributes: attributes,
};

// Initialize the client
const client = BacktraceClient.initialize(options);

You can also include attributes that will be resolved when creating a report:

// BacktraceClientOptions
const options: BacktraceConfiguration = {
    url: 'https://submit.backtrace.io/<universe>/<token>/json',

    // Attach the attributes object
    userAttributes: () => ({
        attribute: getAttributeValue(),
    }),
};

// Initialize the client
const client = BacktraceClient.initialize(options);

Add attributes during application runtime

Global attributes can be set during the runtime once specific data has be loaded (e.g. a user has logged in).

const client = BacktraceClient.initialize(options);
...

client.addAttribute({
    "clientID": "de6faf4d-d5b5-486c-9789-318f58a14476"
})

You can also add attributes that will be resolved when creating a report:

const client = BacktraceClient.initialize(options);
...

client.addAttribute(() => ({
    "clientID": resolveCurrentClientId()
}))

Add attributes to an error report

The attributes list of a BacktraceReport object can be directly modified.

const report: BacktraceReport = new BacktraceReport('My error message', { myReportKey: 'myValue' });
report.attributes['myReportKey'] = 'New value';

File Attachments

Files can be attached to error reports. This can be done when initalizing the BacktraceClient, updating the BacktraceClient, or dynamically for specific reports. When including attachments in BacktraceClient, all files will be uploaded with each report.

// Import attachment types from @backtrace/nestjs
import { BacktraceStringAttachment, BacktraceUint8ArrayAttachment, BacktraceFileAttachment } from "@backtrace/node";

// BacktraceStringAttachment should be used for text object like a log file, for example
const stringAttachment = new BacktraceStringAttachment("logfile.txt", "This is the start of my log")

// Buffer attachment is an attachment type dedicated to store buffer data
const bufferAttachment = new BacktraceBufferAttachment('buffer-attachment.txt', Buffer.from('sample'));

// File attachment is an attachment type dedicated for streaming files
const fileAttachment = new BacktraceFileAttachment('/path/to/sample/file');

// BacktraceClientOptions
const options = {
    url: "https://submit.backtrace.io/<universe>/<token>/json",

    // Attach the files to all reports
    attachments: [path.join('/path/to/attachment'), stringAttachment],
}

const client = BacktraceClient.initialize(options);

// Later decide to add an attachment to all reports
client.addAttachment(bufferAttachment)

// After catching an exception and generating a report
try {
    throw new Error("Caught exception!")
} catch (error) {
    const report = const report = new BacktraceReport(error, {}, [fileAttachment])
    client.send(report);
}

Breadcrumbs

Breadcrumbs are snippets of chronological data tracing runtime events. This SDK records a number of events by default, and manual breadcrumbs can also be added.

(Breadcrumbs feature documentation)

Breadcrumbs Configuration

| Option Name | Type | Description | Default | Required? | | -------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------ | | enable | Boolean | Determines if the breadcrumbs support is enabled. By default the value is set to true. | true | - [ ] | | logLevel | BreadcrumbLogLevel | Specifies which log level severity to include. By default all logs are included. | All Logs | - [ ] | | eventType | BreadcrumbType | Specifies which breadcrumb type to include. By default all types are included. | All Types | - [ ] | | maximumBreadcrumbs | Number | Specifies maximum number of breadcrumbs stored by the library. By default, only 100 breadcrumbs will be stored. | 100 | - [ ] | | intercept | (breadcrumb: RawBreadcrumb) => RawBreadcrumb | undefined; | Inspects breadcrumb and allows to modify it. If the undefined value is being returned from the method, no breadcrumb will be added to the breadcrumb storage. | All Breadcrumbs | - [ ] |

import { BacktraceClient, BacktraceConfiguration } from '@backtrace/nestjs';

// BacktraceClientOptions
const options: BacktraceConfiguration = {
    // ignoring all but breadcrumbs config for simplicity
    breadcrumbs: {
        // breadcrumbs configuration
    },
};

// Initialize the client
const client = BacktraceClient.initialize(options);

Default Breadcrumbs

| Type | Description | | ------- | ------------------------------------------------------------------------ | | Console | Adds a breadcrumb every time console log is being used by the developer. |

Intercepting Breadcrumbs

If PII or other information needs to be filtered from a breadcrumb, you can use the intercept function to skip or filter out the sensitive information. Any RawBreadcrumb returned will be used for the breadcrumb. If undefined is returned, no breadcrumb will be added.

Manual Breadcrumbs

In addition to all of the default breadcrumbs that are automatically collected, you can also manually add breadcrumbs of your own.

client.breadcrumbs?.info('This is a manual breadcrumb.', {
    customAttr: 'wow!',
});

Application Stability Metrics

The Backtrace NestJS SDK has the ability to send usage Metrics to be viewable in the Backtrace UI.

(Stability Metrics feature documentation)

Metrics Configuration

| Option Name | Type | Description | Default | Required? | | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------ | | metricsSubmissionUrl | String | Metrics server hostname. By default the value is set to https://events.backtrace.io. | https://events.backtrace.io | - [ ] | | enable | Boolean | Determines if the metrics support is enabled. By default the value is set to true. | true | - [ ] | | autoSendInterval | Number | Indicates how often crash free metrics are sent to Backtrace. The interval is a value in ms. By default, session events are sent on application startup/finish, and every 30 minutes while the application is running. If the value is set to 0. The auto send mode is disabled. In this situation the application needs to maintain send mode manually. | On application startup/finish | - [ ] | | size | Number | Indicates how many events the metrics storage can store before auto submission. | 50 | - [ ] |

Metrics Usage

// metrics will be undefined if not enabled
client.metrics?.send();

Offline database support

The Backtrace NestJS SDK can cache generated reports and crashes to local disk before sending them to Backtrace. This is recommended; in certain configurations NestJS applications can crash before the SDK finishes submitting data, and under slow internet conditions your application might wait in a closing window until the HTTP submission finishes. In such an event cached reports will be sent on next application launch.

With offline database support you can:

• cache your reports when the user doesn't have an internet connection or the service is unavailable,
• capture crashes,
• manually decide whether or not to send reports, and when.

Offline database support is disabled by default. To enable it, please add "enable: true" and the path to the directory where Backtrace can store crash data.

const client = BacktraceClient.initialize({
    // ignoring all but database config for simplicity
    database: {
        enable: true,
        path: '/path/to/the/database/directory',
        captureNativeCrashes: true,
    },
});

// manually send and keep the data on connection issue
client.database.send();
// manually send and remove all data no matter if received success or not.
client.database.flush();

Database Configuration

| Option Name | Type | Description | Default | Required? | | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------ | | enabled | Boolean | Enable/disable offline database support. | false | - [x] | | path | String | Local storage path for crash data. | - | - [x] | | createDatabaseDirectory | Boolean | Allow the SDK to create the offline database directory. | true | | autoSend | Boolean | Sends reports to the server based on the retry settings. If the value is set to 'false', you can use the Flush or Send methods as an alternative. | true | | maximumNumberOfRecords | Number | The maximum number of reports stored in the offline database. When the limit is reached, the oldest reports are removed. If the value is equal to '0', then no limit is set. | 8 | | retryInterval | Number | The amount of time (in ms) to wait between retries if the database is unable to send a report. | 60 000 | | maximumRetries | Number | The maximum number of retries to attempt if the database is unable to send a report. | 3 | | captureNativeCrashes | Boolean | Capture and symbolicate stack traces for native crashes if the runtime supports this. A crash report is generated, stored locally, and uploaded upon next start. | false |

Native crash support

The Backtrace NestJS SDK can capture native crashes generated by a NestJS application such as Assert/OOM crashes. In order to collect them, the SDK uses the NestJS's process.report API. After setting up the native crash support, your process.report settings may be overridden and your crash data might be created in the database directory.

Database records sent in the next session may not have some information about the crashing session such as attributes or breadcrumbs. To reduce database record size, attachment support was limited only to file attachments.

Manual database operations

Database support is available in the client options with the BacktraceDatabase object. You can use it to manually operate on database records.

Advanced SDK Features

BacktraceClient

BacktraceClient is the main SDK class. Error monitoring starts when this singleton object is instantiated, and it will compose and send reports for unhandled errors and unhandled promise rejections. It can also be used to manually send reports from exceptions and rejection handlers. Do not create more than one instance of this object.

BacktraceClientOptions

The following options are available for the BacktraceClientOptions passed when initializing the BacktraceClient.

| Option Name | Type | Description | Default | Required? | | ----------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------------------------ | | url | String | Submission URL to send errors to | | - [x] | | token | String | The submission token for error injestion. This is required only if submitting directly to a Backtrace URL. (uncommon) | | - [ ] | | userAttributes | Dictionary | Additional attributes that can be filtered and aggregated against in the Backtrace UI. | | - [ ] | | attachments | BacktraceAttachment[] | Additional files to be sent with error reports. See File Attachments | | - [ ] | | beforeSend | (data: BacktraceData) => BacktraceData | undefined | Triggers an event every time an exception in the managed environment occurs, which allows you to skip the report (by returning a null value) or to modify data that library collected before sending the report. You can use the BeforeSend event to extend attributes or JSON object data based on data the application has at the time of exception. See Modify/skip error reports) | | - [ ] | | skipReport | (report: BacktraceReport) => boolean | If you want to ignore specific types of error reports, we recommend that you use the skipReport callback. By using it, based on the data generated in the report, you can decide to filter the report, or send it to Backtrace. | | - [ ] | | captureUnhandledErrors | Boolean | Enable unhandled errors | true | - [ ] | | captureUnhandledPromiseRejections | Boolean | Enable unhandled promise rejection | true | - [ ] | | timeout | Integer | How long to wait in ms before timing out the connection | 15000 | - [ ] | | ignoreSslCertificate | Boolean | Ignore SSL Certificate errors | false | - [ ] | | rateLimit | Integer | Limits the number of reports the client will send per minute. If set to '0', there is no limit. If set to a value greater than '0' and the value is reached, the client will not send any reports until the next minute. | 0 | - [ ] | | metrics | BacktraceMetricsOptions | See Backtrace Stability Metrics | | - [ ] | | breadcrumbs | BacktraceBreadcrumbsSettings | See Backtrace Breadcrumbs | | - [ ] | | database | BacktraceDatabaseSettings | See Backtrace Database | | - [ ] |

Manually send an error

There are several ways to send an error to Backtrace. For more details on the definition of client.send() see Methods below.

// send as a string
await client.send('This is a string!');

// send as an Error
await client.send(new Error('This is an Error!'));

// as a BacktraceReport (string)
await client.send(new BacktraceReport('This is a report with a string!'));

// as a BacktraceReport (Error)
await client.send(new BacktraceReport(new Error('This is a report with a string!')));

Modify/skip error reports

A BeforeSend event is triggered when an exception in the managed environment occurs to which you can attach a handler. You can use the BeforeSend event to scrub PII, or extend attributes or JSON object data based on data your application has at the time of exception. A report can be skipped sompletely by returning a null value.

const client = BacktraceClient.initialize({
    url: SUBMISSION_URL,
    beforeSend: (data: BacktraceData) => {
        // skip the report by returning a null from the callback
        if (!shouldSendReportToBacktrace(data)) {
            return undefined;
        }
        // apply custom attribute
        data.attributes['new-attribute"] = 'apply-data-in-callback';
        return data;
    },
});

SDK Method Overrides

BacktraceClient.builder is used to override default BacktraceClient methods. File and http operation overrides, for example, can be used to implement custom encryption for data at rest or in motion.

Do not use these operations to modify the data objects. See Modify/skip error reports for the correct method to modify a report before sending it to Backtrace.

const client = BacktraceClient.builder(options)
    .useRequestHandler(requestHandler)
    .useBreadcrumbSubscriber(breadcrumbSubscriber)
    .addAttributeProvider(attributeProvider)
    .build();