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"],

  // 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 `uncaughtException` in Node.js
  // 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,

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

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