Configuration

Configuration file (server-side only)

When using the JavaScript client in a Node.js environment, you can configure Honeybadger using a configuration file in your project’s root directory, such as honeybadger.config.js or honeybadger.config.ts. The configuration file should export an object with the configuration.

An example configuration file is shown below:

honeybadger.config.js

module.exports = {
  apiKey: process.env.HONEYBADGER_API_KEY,
  environment: process.env.NODE_ENV,
  revision: process.env.HONEYBADGER_REVISION,
  // etc.
};

Configuration options

All of the available configuration options are shown below:

Honeybadger.configure({
  // Honeybadger API key (required)
  apiKey: "",

  // The revision of the current deploy
  revision: "",

  // Project root
  projectRoot: "http://my-app.com",

  // Environment
  environment: "production",

  // Defaults to the server's hostname in Node.js
  hostname: "badger01",

  // Environments which will not report data
  developmentEnvironments: ["dev", "development", "test"],

  // Override `developmentEnvironments` to explicitly enable/disable error reporting
  // reportData: true,

  // Key values to filter from request data. Matches are partial, so "password"
  // and "password_confirmation" will both be filtered
  filters: ["creditcard", "password"],

  // Tags to apply to every reported error. Accepts an array of strings or a
  // comma-separated string. See "Tagging errors".
  tags: [],

  // Component (optional)
  component: "",

  // Action (optional)
  action: "",

  // Should unhandled errors be reported?
  // This option uses `window.onerror` in browsers and `uncaughtException` in Node.js
  enableUncaught: true,

  // Executed after an uncaught exception is reported in Node.js.
  // See "Uncaught exceptions" in the Node.js integration guide.
  // afterUncaught: (error) => {},

  // Should unhandled Promise rejections be reported?
  enableUnhandledRejection: true,

  // Enable breadcrumbs collection
  breadcrumbsEnabled: true,

  // Automatically send console logs to Honeybadger Insights
  eventsEnabled: true,

  // Collector Host
  // If you are using our EU stack, this should be set to "https://eu-api.honeybadger.io".
  endpoint: "https://api.honeybadger.io",

  // The maximum number of breadcrumbs to include with error reports
  maxBreadcrumbs: 40,

  // The maximum depth allowed in deeply-nested objects
  maxObjectDepth: 8,

  // The logger to use. Should behave like `console`
  logger: console,

  // Output Honeybadger debug messages to the logger
  debug: false,
});

The following additional options are available in browser environments:

Honeybadger.configure({
  // Send notifications asynchronously
  async: true,

  // Endpoint to submit user feedback for errors. See "Collecting User Feedback".
  // If you are using our EU stack, this should be set to "https://eu-api.honeybadger.io/v2/feedback".
  userFeedbackEndpoint: "https://api.honeybadger.io/v2/feedback",

  // Limit the maximum number of errors the client will send to Honeybadger
  // after page load. Default is unlimited (undefined)
  maxErrors: 20,

  // Ignore errors that originate from browser extensions (chrome-extension://,
  // moz-extension://, safari-extension://, safari-web-extension://).
  // Errors filtered by this option do not count against `maxErrors`.
  ignoreBrowserExtensionErrors: false,

  // Enable breadcrumbs collection
  breadcrumbsEnabled: true,
  // You can also selectively configure these types of breadcrumbs:
  // breadcrumbsEnabled: {
  //   dom: true,
  //   network: true,
  //   navigation: true,
  //   console: true
  // }

  // Element attributes to prefer when naming elements in click breadcrumbs.
  // See "Naming elements in click breadcrumbs" below.
  breadcrumbsSelectorAttributes: ["data-hb-name"],
});

The following additional options are available in serverless environments (currently AWS Lambda):

Honeybadger.configure({
  // Report a warning to Honeybadger when a Lambda function is about to reach
  // its configured time limit
  reportTimeoutWarning: true,

  // How close (in milliseconds) the function must get to the Lambda time
  // limit before the timeout warning is reported
  timeoutWarningThresholdMs: 50,
});

See Timeout warning in the Node.js integration guide for details.

Naming elements in click breadcrumbs

When you click an element, Honeybadger records a ui.click breadcrumb containing a CSS selector for that element. By default the selector is built from each element’s tag, id, and classes, which can be hard to read in apps that use utility CSS frameworks such as Tailwind:

body > div#root > main > div.flex.min-h-screen.flex-col.font-sans.antialiased > ...

To make these breadcrumbs legible, add a data-hb-name attribute to the elements you care about. When a clicked element — or one of its ancestors — has the attribute, its value replaces that element’s selector segment, and the nearest named ancestor anchors the selector, so everything above it is dropped. Given this markup:

<div data-hb-name="deal-card">
  <h3 class="text-left font-semibold">Acme Corp</h3>
</div>

Clicking the heading records the selector deal-card > h3.text-left.font-semibold instead of the full chain from <body>.

Use breadcrumbsSelectorAttributes to reuse attributes you already have, such as the test IDs from your test suite. The first attribute in the list that is present on an element wins:

Honeybadger.configure({
  breadcrumbsSelectorAttributes: ["data-hb-name", "data-testid"],
});

Set the option to [] to disable this behavior and always build selectors from tags, ids, and classes.

Configuring with environment variables

Unlike some of our other client libraries, honeybadger.js does not automatically read configuration from environment variables; to use environment variables, you must configure Honeybadger like this:

Honeybadger.configure({
  apiKey: process.env.HONEYBADGER_API_KEY,
  environment: process.env.NODE_ENV,
  revision: process.env.HONEYBADGER_REVISION,
  // etc.
});

Note that process.env may not be available outside of Node.js by default (it depends on your JavaScript build system). For example, in Webpack you need to use environmentPlugin to make process.env keys available in source files.

beforeNotify handlers

beforeNotify handlers run before each notice (error report) is sent to Honeybadger. There are two cases this might be useful:

1. Filtering out unwanted error reports by returning false from a handler
2. Sanitizing or enhancing notice data before being sent to Honeybadger

Usage examples

Sanitizing notice data:

Honeybadger.beforeNotify((notice) => {
  if (/creditCard/.test(notice.url)) {
    notice.url = "[FILTERED]";
  }
});

Adding additional context to notice data:

Honeybadger.beforeNotify((notice) => {
  notice.context.session_id = MyApp.sessionId;
});

Adding additional context to notice data from an async source:

Honeybadger.beforeNotify(async (notice) => {
  notice.context.state = await MyApp.getState();
});

Skipping a notice:

Honeybadger.beforeNotify((notice) => {
  if (/third-party-domain/.test(notice.stack)) {
    return false;
  }
});

afterNotify handlers

afterNotify handlers run after each notice (error report) is sent to Honeybadger. Here are two cases where this is useful:

1. Displaying the ID of the Honeybadger notice to users
2. Handling errors if the Honeybadger API rejects the notice

Usage examples

Log a URL to the error report in Honeybadger:

Honeybadger.afterNotify((err, notice) => {
  if (err) {
    return console.log(`Honeybadger notification failed: ${err}`);
  }
  console.log(
    `Honeybadger notice: https://app.honeybadger.io/notice/${notice.id}`,
  );
});

An afterNotify handler can also be attached to a single error report:

Honeybadger.notify("testing", {
  afterNotify: (err, notice) => console.log(err || notice.id),
});

Notice properties

The following notice properties are available in notice objects:

• notice.stack - The stack trace (read only)
• notice.backtrace - The parsed backtrace object
• notice.name - The exception class name
• notice.message - The error message
• notice.url - The current url
• notice.projectRoot - The root url
• notice.environment - Name of the environment. example: “production”
• notice.component - Similar to a rails controller name. example: “users”
• notice.action - Similar to a rails action name. example: “create”
• notice.fingerprint - A unique fingerprint, used to customize grouping of errors in Honeybadger
• notice.context - The context object
• notice.tags - A string comma-separated list of tags
• notice.params - An object of request parameters
• notice.session - An object of request session key/values
• notice.headers - An object of request headers
• notice.cookies - An object of cookie key/values. May also be sent as a string in the document.cookie “foo=bar;bar=baz” format.

The following additional notice properties are available in afterNotify handlers:

• notice.id - The UUID of the error in Honeybadger