rollbar-utils

This code provides utility functions to handle and log errors with Rollbar integration in a Node.js environment, including rescheduling tasks and triggering Rollbar error logging based on certain conditions.

Lazy man's Implementation

index.ts

import RollbarUtil from "@gatekeeper_technology/rollbar-utils";

let rollbar: RollbarUtil;

export async function run(this: TaskContext, params: any) {
    console.log(`🏁 Task started (in ${CloudCode.task.env}) with params: ${JSON.stringify(params ?? (params = {}), null, 2)}`);
    rollbar = new RollbarUtil({
        access_token: process.env.ROLLBAR_ACCESS_TOKEN,
        params: params,
        self: this
    });

    try {
        await runTask.call(this, request_object);
    } catch (error) {
        await rollbar.handleError(error);
    }
}

index.js

• When working with .js files, you can import the package as shown below:

  const { default: RollbarUtil } = require("@gatekeeper_technology/rollbar-utils");

package.json

• No need to import Rollbar
• Manually update your dependency

  "dependencies": {
    "@gatekeeper_technology/rollbar-utils": "<latest_version>",
    "@journeyapps/cloudcode": "1.12.0"
  },

tsconfig.json (only for TypeScript):

• Replace your tsconfig.json file with:

{
    "extends": "@journeyapps/cloudcode-build/task-tsconfig",
    "compilerOptions": {
        "esModuleInterop": true,
        "allowJs": false,
        "skipLibCheck": true
    }
}

• Don't forget to register your Rollbar access token using deployment environment variable ROLLBAR_ACCESS_TOKEN. For testing, you can use the token that is pinned in the #rollbar-testing-spam Slack channel

• Note: If you get an linting error of copying and pasting, try refreshing OXIDE.

Detailed Usage

Handle errors using in your main catch

await rollbar.handleError(error);

Or with options:

await rollbar.handleError(error, { reschedule_task: false });

Flags

• env: Specifies environment(s) to log or reschedule errors. Default is "production".
  • Can be string or string[]
• reschedule_task: Auto-reschedule task on failure. Default is true.
• trigger_rollbar: Log errors to Rollbar. Default is true.

Customizing Error Behavior with throwError

The throwError function allows you to throw custom errors with configurable settings. You can control whether to trigger Rollbar logging or to reschedule the task. By default, the settings are { trigger_rollbar: true, reschedule_task: false }.

Here's how to use throwError:

    rollbar.throwError("Will not trigger rollbar", { trigger_rollbar: false });
    rollbar.throwError("Will trigger rollbar, but not reschedule", { trigger_rollbar: true, reschedule_task: false });
    rollbar.throwError("Will not trigger rollbar, and not reschedule", { trigger_rollbar: false, reschedule_task: false });

Note: All actions are implemented only in the specified environments, which defaults to "production."

Custom Error Handling

Our utility provides fine-grained control over how certain types of errors are managed. This section explains how to work with two specific custom errors: status-not-pending and attachments-uploading.

status-not-pending

This type of error is considered a "blocking" error. If such an error occurs, the task will not be retried.

attachments-uploading

For this error type, Rollbar logging is conditional based on the retry count. The utility will only log a Rollbar error on the final retry.

Changelog

[1.2.2] - 2024-07-23

Updated

• Dependencies to latest versions

[1.2.1] - 2024-01-08

Added

• Function to add object ids to the CC parameters for objects in the CC parameters.

[1.2.0] - 2023-10-12

Added

• Introduced throwError function for more granular error handling.
• Allows custom errors that can be set to either retry or not.
• Can also be set to log or not log in Rollbar.

Changed

• Refactored repository structure from a single file to a multi-file architecture.
• Improves modularity and maintainability of the code.
• Improved the README

[1.1.2] - 2023-09-29

Changed

• Changed the Rollbar Config Validation to only log the errors in the console and not throw the Errors.
• If the env is not set, it defaults to 'testing'
• If the trace_id is not set, it defaults to 'not_applicable'

[1.1.1] - 2023-09-27

Added

• Enhanced error analysis: The package now checks the error's name, message, and cause to determine whether the error should be ignored.

Changed

• Updated README.md with both concise and comprehensive usage instructions.
• Renamed the env_to_error flag to env.
• The env flag now specifies the environments for which the CC Task may trigger rollbar and reschedule.
• All console.warn or console.error are changed to console.log, due to not always logging the messages.

[1.1.0] - 2023-09-15

Added

• 'status-not-pending' errors no longer rescheduling task or log on rollbar.

Changed

• Converted functions to a Class
• Improve console logging.
• Better Exception handling

Fixed

• Typo
• Edge case where if a CC Task did not reschedule, rollbar would retrigger even if asked not to.

[1.0.9] - 2023-09-15

Fixed

• Reverted hook function change in version 1.0.7.

[1.0.8] - 2023-09-15

Fixed

• A bug where the context could not be found due to the hook function being async.

[1.0.7] - 2023-09-15

Changed

• Changed functions to hook functions.

Fixed

• A bug where the error names were not read correctly.
• A bug where a null/undefined retry_count stopped the task from retrying.

[1.0.6] - 2023-09-01

Changed

• More improved console logs!

Fixed

• a bug that attempted to log task even without an rollbar access token

[1.0.5] - 2023-09-01

Added

• Added comments on the two exported functions so that it helps developers.
• Error handling for inside the package.

Fixed

• A bug where the 'shouldReschedule' flag was ignored.

[1.0.4] - 2023-09-01

Added

• Added optional 'shouldReschedule' flag.

Removed

• Removed TS's type checking on 'this'.

[1.0.3] - 2023-09-01

Added

• Added 'attachments-uploading' check.

Changed

• Implemented 'trigger_rollbar' flag.
• Improved on console logs.

Fixed

• Typo fixed.

[1.0.2] - 2023-08-18

Added

• Added .d.ts files.

Fixed

• Resolved ToDos

[1.0.1] - 2023-08-18

Changed

• Made the package public

[1.0.0] - 2023-07-21

Added

• Initial functionality that logs errors through rollbar, if it does not reschedule itself.