@gatekeeper_technology/rollbar-utils

中文文档
1.2.5发布于 2026/07/10ISCTypeScriptCommonJS近 30 天下载 2.3万

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.

原始使用文档
文档目录30 节
  1. Lazy man's Implementation
  2. index.ts
  3. index.js
  4. package.json
  5. tsconfig.json (only for TypeScript):
  6. Detailed Usage
  7. Handle errors using in your main catch
  8. Customizing Error Behavior with throwError
  9. Custom Error Handling
  10. status-not-pending
  11. attachments-uploading
  12. Changelog
  13. [1.2.4] - 2025-01-29
  14. [1.2.3] - 2024-08-07
  15. [1.2.2] - 2024-07-23
  16. [1.2.1] - 2024-01-08
  17. [1.2.0] - 2023-10-12
  18. [1.1.2] - 2023-09-29
  19. [1.1.1] - 2023-09-27
  20. [1.1.0] - 2023-09-15
  21. [1.0.9] - 2023-09-15
  22. [1.0.8] - 2023-09-15
  23. [1.0.7] - 2023-09-15
  24. [1.0.6] - 2023-09-01
  25. [1.0.5] - 2023-09-01
  26. [1.0.4] - 2023-09-01
  27. [1.0.3] - 2023-09-01
  28. [1.0.2] - 2023-08-18
  29. [1.0.1] - 2023-08-18
  30. [1.0.0] - 2023-07-21

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.4] - 2025-01-29

Updated

  • Dependencies to latest versions

[1.2.3] - 2024-08-07

Updated

  • Dependencies to latest versions

[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.

版本与发布记录

@gatekeeper_technology/rollbar-utils 共发布 19 个版本,首次发布于 2023/07/21;过去 12 个月发布了 1 个版本。

版本发布日期距今
1.2.5latest2026/07/104 个月前
1.2.42025/01/291.8 年前
1.2.32024/08/072 年前
1.2.22024/07/232 年前
1.2.12024/01/082 年前
1.2.02023/10/133 年前

关于 @gatekeeper_technology/rollbar-utils 的常见问题

@gatekeeper_technology/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.

如何安装 @gatekeeper_technology/rollbar-utils?

在项目目录运行 npm install @gatekeeper_technology/rollbar-utils,或使用 pnpm add / yarn add / bun add。

@gatekeeper_technology/rollbar-utils 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gatekeeper_technology/rollbar-utils 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@gatekeeper_technology/rollbar-utils 可以商用吗?

@gatekeeper_technology/rollbar-utils 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gatekeeper_technology/rollbar-utils 的下载量有多少?

根据 npm 官方下载统计,@gatekeeper_technology/rollbar-utils 在 2026/10/16 – 2026/11/14 这 30 天内被下载 23,278 次,日均约 776 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gatekeeper_technology/rollbar-utils 还在维护吗?

最新版本 1.2.5 发布于 2026/07/10(4 个月前);至今共发布 19 个版本,其中过去 12 个月发布了 1 个;首次发布于 2023/07/21。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。