diff --git a/examples/sdk/node/src/index.ts b/examples/sdk/node/src/index.ts index e0c15d46..aea7327a 100644 --- a/examples/sdk/node/src/index.ts +++ b/examples/sdk/node/src/index.ts @@ -21,7 +21,7 @@ const client = BacktraceClient.initialize({ }, }, database: { - enabled: true, + enable: true, path: path.join(process.cwd(), 'database'), captureNativeCrashes: true, createDatabaseDirectory: true, diff --git a/packages/node/README.md b/packages/node/README.md index 5eff02b3..071a979a 100644 --- a/packages/node/README.md +++ b/packages/node/README.md @@ -194,7 +194,7 @@ and manual breadcrumbs can also be added. | `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 | | ```ts -import { BacktraceClient, BacktraceConfiguration } from '@backtrace-labs/ndoe'; +import { BacktraceClient, BacktraceConfiguration } from '@backtrace-labs/node'; // BacktraceClientOptions const options: BacktraceConfiguration = { @@ -259,70 +259,64 @@ client.metrics?.send(); ### Offline database support -The Backtrace Node SDK allows to store generated reports and crashes on the hard drive before sending them to Backtrace. -Based on your node configuration, your application might crash before the SDK finishes submitting data. In addition to -that if the application user has a slow Internet connection, your application might wait in a closing window until the -HTTP submission finishes. To prevent this situation, we recommend to use the database solution. By using it, you can: +The Backtrace Node SDK can cache generated reports and crashes to local disk before sending them to Backtrace. This is +recommended; in certain configurations Node 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 occurs cached reports will be sent on next application launch. + +With offline database support you can: - cache your reports when the user doesn't have Internet connection or the service is unavailable, -- capture crashes -- manually decide when to send them or not +- capture crashes, +- manually decide when to send them or not. By default the offline database support is disabled. To enable it, please add "enable: true" and the path to the directory where Backtrace can store crash data. +```ts +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 | Determine if the Database is enabled. | false | | -| `path` | String | Path where the SDK can store data. | - | | -| `createDatabaseDirectory` | Boolean | Determine if the directory should be auto created by the SDK. | true | | +| `enabled` | Boolean | Enable/disable offline database support. | false | | +| `path` | String | Local storage path for crash data. | - | | +| `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 | Captures and symbolicates stack traces for native crashes if the runtime supports this. A crash report is generated, stored locally, and uploaded upon next start. | false | +| `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 Node SDK allows to capture native crashes generated by the node application such as Assert/OOM crashes. In -order to collect them, the SDK uses the Node's `process.report` API. After setting up the native crash support, your -`process.report` settings might be overridden and your crash data might be created in the database directory. +The Backtrace Node SDK can capture native crashes generated by a Node application such as Assert/OOM crashes. In order +to collect them, the SDK uses the Node'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 might 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. +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. You can use it to manually operate on database records. The -database object allows you to: - -- add manually your Backtrace data, -- get all records, -- count all records, -- dispose of the database, -- remove the record, -- flush all records - send and forget, -- send manually all records. - -```ts -const client = BacktraceClient.initialize({ - // ignoring all but database config for simplicity - database: { - enabled: true, - path: '/path/to/the/database/directory', - captureNativeCrashes: true, - }, -}); - -// manuall send and keep the data on connection issue -client.database.send(); -// manuall send and remove all data no matter if received success or not. -client.database.flush(); -``` +Database support is available in the client options with the BacktraceDatabase object. You can use it to manually +operate on database records. Options are detailed in [BacktraceDatabase Methods](#backtracedatabase-methods). ## Advanced SDK Features @@ -385,7 +379,7 @@ The following options are available for the BacktraceClientOptions passed when i | Name | Return Type | Description | | ----------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `enable` | Boolean | Determines if the database is enabled | +| `enabled` | Boolean | Determines if the database is enabled | | `start()` | Boolean | Starts the database | | `add(backtraceData: Backtracedata, attachments: BacktraceAttachment[])` | BacktraceDatabaseRecord \| undefined | Adds manually a data object to the database. If the database is not available or the record cannot be stored on the hard drive, the add method can return undefined. | | `get()` | BacktraceDatabaseRecord[] | Returns all records stored in the database | diff --git a/packages/node/src/BacktraceClient.ts b/packages/node/src/BacktraceClient.ts index 07c3910b..e4f50ae0 100644 --- a/packages/node/src/BacktraceClient.ts +++ b/packages/node/src/BacktraceClient.ts @@ -195,7 +195,7 @@ export class BacktraceClient extends BacktraceCoreClient { return; } - if (!this.options.database?.enabled) { + if (!this.options.database?.enable) { return; } diff --git a/packages/node/src/database/BacktraceDatabaseFileStorageProvider.ts b/packages/node/src/database/BacktraceDatabaseFileStorageProvider.ts index 3a06bd04..288ead44 100644 --- a/packages/node/src/database/BacktraceDatabaseFileStorageProvider.ts +++ b/packages/node/src/database/BacktraceDatabaseFileStorageProvider.ts @@ -25,11 +25,11 @@ export class BacktraceDatabaseFileStorageProvider implements BacktraceDatabaseSt if (!options) { return undefined; } - if (!options.enabled) { + if (!options.enable) { return undefined; } - if (options.enabled && !options.path) { + if (options.enable && !options.path) { throw new Error( 'Missing mandatory path to the database. Please define the database.path option in the configuration.', ); diff --git a/packages/sdk-core/src/BacktraceCoreClient.ts b/packages/sdk-core/src/BacktraceCoreClient.ts index d43f8693..64bc5a0f 100644 --- a/packages/sdk-core/src/BacktraceCoreClient.ts +++ b/packages/sdk-core/src/BacktraceCoreClient.ts @@ -117,7 +117,7 @@ export abstract class BacktraceCoreClient { ]); this.attachments = options.attachments ?? []; - if (databaseStorageProvider && options?.database?.enabled === true) { + if (databaseStorageProvider && options?.database?.enable === true) { this._database = new BacktraceDatabase( this.options.database, databaseStorageProvider, diff --git a/packages/sdk-core/src/model/configuration/BacktraceDatabaseConfiguration.ts b/packages/sdk-core/src/model/configuration/BacktraceDatabaseConfiguration.ts index cf553022..f5a131a2 100644 --- a/packages/sdk-core/src/model/configuration/BacktraceDatabaseConfiguration.ts +++ b/packages/sdk-core/src/model/configuration/BacktraceDatabaseConfiguration.ts @@ -2,7 +2,7 @@ export interface EnabledBacktraceDatabaseConfiguration { /** * Determine if the Database is enabled */ - enabled: true; + enable: true; /** * Path where the SDK can store data. */ @@ -46,11 +46,11 @@ export interface EnabledBacktraceDatabaseConfiguration { } export interface DisabledBacktraceDatabaseConfiguration - extends Omit, 'enabled'> { + extends Omit, 'enable'> { /** - * Determine if the Database is enabled + * Determine if the Database is enable */ - enabled?: false; + enable?: false; } export type BacktraceDatabaseConfiguration = diff --git a/packages/sdk-core/src/modules/database/BacktraceDatabase.ts b/packages/sdk-core/src/modules/database/BacktraceDatabase.ts index 271b2e6f..71ff6d53 100644 --- a/packages/sdk-core/src/modules/database/BacktraceDatabase.ts +++ b/packages/sdk-core/src/modules/database/BacktraceDatabase.ts @@ -43,7 +43,7 @@ export class BacktraceDatabase { return this._enabled; } - if (this._options?.enabled === false) { + if (this._options?.enable === false) { return false; } diff --git a/packages/sdk-core/tests/database/databaseContextMemoryStorageTests.spec.ts b/packages/sdk-core/tests/database/databaseContextMemoryStorageTests.spec.ts index 7bf850be..2e032f78 100644 --- a/packages/sdk-core/tests/database/databaseContextMemoryStorageTests.spec.ts +++ b/packages/sdk-core/tests/database/databaseContextMemoryStorageTests.spec.ts @@ -7,7 +7,7 @@ import { testStorageProvider } from '../mocks/testStorageProvider'; describe('Database context memory storage tests', () => { const testDatabaseSettings = { - enabled: true, + enable: true, autoSend: false, // this option doesn't matter because we mock the database provider // interface. However, if bug happen we want to be sure to not create diff --git a/packages/sdk-core/tests/database/databaseContextValidationTests.spec.ts b/packages/sdk-core/tests/database/databaseContextValidationTests.spec.ts index 41cfda12..cc39c5ee 100644 --- a/packages/sdk-core/tests/database/databaseContextValidationTests.spec.ts +++ b/packages/sdk-core/tests/database/databaseContextValidationTests.spec.ts @@ -7,7 +7,7 @@ import { testStorageProvider } from '../mocks/testStorageProvider'; describe('Database context validation tests', () => { describe('Record overflow tests', () => { const testDatabaseSettings: BacktraceDatabaseConfiguration = { - enabled: true, + enable: true, autoSend: false, // this option doesn't matter because we mock the database provider // interface. However, if bug happen we want to be sure to not create diff --git a/packages/sdk-core/tests/database/databaseRecordBatchTests.spec.ts b/packages/sdk-core/tests/database/databaseRecordBatchTests.spec.ts index cc1a0ba0..9e016284 100644 --- a/packages/sdk-core/tests/database/databaseRecordBatchTests.spec.ts +++ b/packages/sdk-core/tests/database/databaseRecordBatchTests.spec.ts @@ -23,7 +23,7 @@ describe('Database record batch tests', () => { const client = BacktraceTestClient.buildFakeClient( { database: { - enabled: true, + enable: true, autoSend: true, path: path.join(__dirname, 'database'), maximumRetries, @@ -56,7 +56,7 @@ describe('Database record batch tests', () => { const client = BacktraceTestClient.buildFakeClient( { database: { - enabled: true, + enable: true, autoSend: true, path: path.join(__dirname, 'database'), maximumRetries, diff --git a/packages/sdk-core/tests/database/databaseSendTests.spec.ts b/packages/sdk-core/tests/database/databaseSendTests.spec.ts index 63b01417..919219ba 100644 --- a/packages/sdk-core/tests/database/databaseSendTests.spec.ts +++ b/packages/sdk-core/tests/database/databaseSendTests.spec.ts @@ -9,7 +9,7 @@ describe('Database send tests', () => { jest.clearAllMocks(); }); const testDatabaseSettings: BacktraceDatabaseConfiguration = { - enabled: true, + enable: true, autoSend: false, // this option doesn't matter because we mock the database provider // interface. However, if bug happen we want to be sure to not create diff --git a/packages/sdk-core/tests/database/databaseSetupTests.spec.ts b/packages/sdk-core/tests/database/databaseSetupTests.spec.ts index c0b4ab63..52b0097d 100644 --- a/packages/sdk-core/tests/database/databaseSetupTests.spec.ts +++ b/packages/sdk-core/tests/database/databaseSetupTests.spec.ts @@ -43,7 +43,7 @@ describe('Database setup tests', () => { it('Should not enable the database if the enable option is set to false', () => { const database = new BacktraceDatabase( - { enabled: false }, + { enable: false }, testStorageProvider, new BacktraceReportSubmission( { @@ -62,7 +62,7 @@ describe('Database setup tests', () => { it('Should not enable the database if the storage is not prepared', () => { const database = new BacktraceDatabase( { - enabled: true, + enable: true, path: '/path/to/fake/dir', }, testStorageProvider, diff --git a/packages/sdk-core/tests/database/databaseStorageFlowTests.spec.ts b/packages/sdk-core/tests/database/databaseStorageFlowTests.spec.ts index baadafef..7682e5be 100644 --- a/packages/sdk-core/tests/database/databaseStorageFlowTests.spec.ts +++ b/packages/sdk-core/tests/database/databaseStorageFlowTests.spec.ts @@ -6,7 +6,7 @@ import { testStorageProvider } from '../mocks/testStorageProvider'; describe('Database storage provider flow tests', () => { const testDatabaseSettings = { - enabled: true, + enable: true, autoSend: false, // this option doesn't matter because we mock the database provider // interface. However, if bug happen we want to be sure to not create