feat: add ability to customize Error Groups

New API function called `setErrorGroupCallback` provides a way for you
to customize the `error.group.name` attribute of errors that are
captured by the agent. This attribute controls how the Errors Inbox
functionality groups similar errors together.

`setErrorGroupCallback` accepts one argument: a callback function. This
function can accept an object argument, which contains metadata
associated with an individual error, and must return a string, which
will be used as the Error Group name. The object passed to the callback
function has the following shape:
```
{
  error: Error,
  customAttributes: Object,
  'request.uri': String,
  'http.statusCode': String,
  'http.method': String,
  'error.expected': Boolean
}
```

Author: jmartin4563

api.js

@@ -1739,4 +1739,49 @@ function _filterAttributes(attributes, name) {
   return filteredAttributes
 }
 
+/**
+ * Function for adding a custom callback to generate Error Group names, which
+ * will be used by the Errors Inbox to group similar errors together via the `error.group.name`
+ * agent attribute.
+ *
+ * Provided functions must return a string, and receive an object as an argument,
+ * which contains information related to the Error that occurred, and has the
+ * following format:
+ *
+ * ```
+ * {
+ *   customAttributes: object,
+ *   'request.uri': string,
+ *   'http.statusCode': string,
+ *   'http.method': string,
+ *   error: Error,
+ *   'error.expected': boolean
+ * }
+ * ```
+ *
+ * Calling this function multiple times will replace previously defined functions
+ *
+ * @param {Function} callback - callback function to generate `error.group.name` attribute
+ * @example
+ * function myCallback(metadata) {
+ *   if (metadata['http.statusCode'] === '400') {
+ *     return 'Bad User Input'
+ *   }
+ * }
+ * newrelic.setErrorGroupCallback(myCallback)
+ */
+API.prototype.setErrorGroupCallback = function setErrorGroupCallback(callback) {
+  const metric = this.agent.metrics.getOrCreateMetric(
+    NAMES.SUPPORTABILITY.API + '/setErrorGroupCallback'
+  )
+  metric.incrementCallCount()
+
+  if (!this.shim.isFunction(callback)) {
+    logger.warn('Error Group callback must be a function, Error Group attribute will not be added')
+    return
+  }
+
+  this.agent.errors.errorGroupCallback = callback
+}
+
 module.exports = API

lib/errors/error-collector.js

@@ -36,6 +36,8 @@ class ErrorCollector {
     this.seenStringsByTransaction = Object.create(null)
 
     this.traceAggregator.on('starting error_data data send.', this._onSendErrorTrace.bind(this))
+
+    this.errorGroupCallback = null
   }
 
   _onSendErrorTrace() {
@@ -330,6 +332,10 @@ class ErrorCollector {
       return false
     }
 
+    if (this.errorGroupCallback) {
+      exception.errorGroupCallback = this.errorGroupCallback
+    }
+
     const errorTrace = createError(transaction, exception, this.config)
     this._maybeRecordErrorMetrics(errorTrace, transaction)
 

lib/errors/index.js

@@ -5,6 +5,7 @@
 
 'use strict'
 
+const logger = require('../logger').child({ component: 'errors_lib' })
 const DESTINATIONS = require('../config/attribute-filter').DESTINATIONS
 const props = require('../util/properties')
 const urltils = require('../util/urltils')
@@ -25,6 +26,7 @@ class Exception {
     this.customAttributes = customAttributes || {}
     this.agentAttributes = agentAttributes || {}
     this._expected = expected
+    this.errorGroupCallback = null
   }
 
   getErrorDetails(config) {
@@ -107,9 +109,44 @@ function createError(transaction, exception, config) {
   params.intrinsics[ERROR_EXPECTED_PATH] =
     exception._expected || errorHelper.isExpected(type, message, transaction, config, urltils)
 
+  maybeAddAgentAttributes(params, exception)
+
   return [0, name, message, type, params]
 }
 
+function isValidErrorGroupOutput(output) {
+  return (typeof output === 'string' || output instanceof String) && output !== ''
+}
+
+function maybeAddAgentAttributes(attributes, exception) {
+  if (exception.errorGroupCallback) {
+    const callbackInput = {
+      'error': exception.error,
+      'customAttributes': Object.assign({}, attributes.userAttributes),
+      'request.uri': attributes.agentAttributes['request.uri'],
+      'http.statusCode': attributes.agentAttributes['http.statusCode'],
+      'http.method': attributes.agentAttributes['request.method'],
+      'error.expected': attributes.intrinsics[ERROR_EXPECTED_PATH]
+    }
+
+    try {
+      const callbackOutput = exception.errorGroupCallback(callbackInput)
+
+      if (!isValidErrorGroupOutput(callbackOutput)) {
+        logger.warn('Function provided via setErrorGroupCallback return value malformed')
+        return
+      }
+
+      attributes.agentAttributes['error.group.name'] = callbackOutput
+    } catch (err) {
+      logger.warn(
+        err,
+        'Function provided via setErrorGroupCallback failed, not generating `error.group.name`'
+      )
+    }
+  }
+}
+
 function maybeAddUserAttributes(userAttributes, exception, config) {
   const customAttributes = exception.customAttributes
   if (!config.high_security && config.api.custom_attributes_enabled && customAttributes) {