newrelic 9.13.0 → 9.14.0

package/NEWS.md

@@ -1,3 +1,7 @@
+### v9.14.0 (2023-03-23)
+
+* Added new API function called `setErrorGroupCallback`, which 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. To learn more about this function, please refer to our [example app](https://github.com/newrelic/newrelic-node-examples).
+
 ### v9.13.0 (2023-03-20)
 
 * Updated http instrumentation to no longer remove the `x-new-relic-disable-dt` header when using AWS SDK v3.  This was done to prevent the "The request signature we calculated does not match the signature you provided. Check your key and signing method." error from AWS SDK.

package/api.js

@@ -1739,4 +1739,51 @@ 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) || this.shim.isPromise(callback)) {
+    logger.warn(
+      'Error Group callback must be a synchronous function, Error Group attribute will not be added'
+    )
+    return
+  }
+
+  this.agent.errors.errorGroupCallback = callback
+}
+
 module.exports = API

package/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)
 

package/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) {

package/lib/metrics/normalizer/tx_segment.js

@@ -5,8 +5,6 @@
 
 'use strict'
 
-/* eslint sonarjs/cognitive-complexity: ["error", 17] -- TODO: https://issues.newrelic.com/browse/NEWRELIC-5252 */
-
 const logger = require('../../logger').child({ component: 'tx_segment_normalizer' })
 
 module.exports = TxSegmentNormalizer
@@ -17,7 +15,7 @@ function TxSegmentNormalizer() {
 
 /**
  * This normalize method is wicked. The best bet is to read the spec:
- * https://newrelic.atlassian.net/wiki/pages/viewpage.action?spaceKey=eng&title=Language+agent+transaction+segment+terms+rules
+ * https://source.datanerd.us/agents/agent-specs/blob/main/Metric-Name-Rules-PORTED.md
  *
  * A copy paste of the rules that were followed:
  *  1. Find the first rule where the prefix key matches the prefix of the
@@ -31,11 +29,28 @@ function TxSegmentNormalizer() {
  *  6. Join together the modified segments with slashes, and re-prepend the prefix.
  *
  * @param {string} path - The transaction metric path to normalize.
- * @returns {NormalizationResults} - The results of normalizing the given path.
+ * @returns {{ignore: boolean, matched: boolean, value: string}} - The results of normalizing the given path.
  */
 TxSegmentNormalizer.prototype.normalize = function normalize(path) {
   let currentTerm
   let prefix
+  let result
+  let prev
+
+  const normalizeParts = (part, idx, parts) => {
+    if (part === '' && idx + 1 === parts.length) {
+      return // if this is the last one, don't iterate
+    }
+    if (currentTerm.terms.indexOf(part) === -1) {
+      if (prev === '*') {
+        return
+      }
+      result.push((prev = '*'))
+    } else {
+      result.push((prev = part))
+    }
+  }
+
   for (let i = 0; i < this.terms.length; i++) {
     currentTerm = this.terms[i]
     prefix = currentTerm.prefix
@@ -44,26 +59,10 @@ TxSegmentNormalizer.prototype.normalize = function normalize(path) {
     }
     const fragment = path.slice(prefix.length)
     const parts = fragment.split('/')
-    const result = []
-    let prev
-    let segment
-
-    for (let j = 0; j < parts.length; j++) {
-      segment = parts[j]
+    result = []
 
-      if (segment === '' && j + 1 === parts.length) {
-        break
-      }
+    parts.forEach(normalizeParts)
 
-      if (currentTerm.terms.indexOf(segment) === -1) {
-        if (prev === '*') {
-          continue
-        }
-        result.push((prev = '*'))
-      } else {
-        result.push((prev = segment))
-      }
-    }
     logger.trace('Normalizing %s because of rule: %s', path, currentTerm)
     return {
       matched: true, // To match MetricNormalizer

package/lib/shimmer.js

@@ -352,33 +352,15 @@ const shimmer = (module.exports = {
     shimmer.unwrapMethod(Module, 'Module', '_load')
   },
 
-  bootstrapInstrumentation: function bootstrapInstrumentation(agent) {
-    // Instrument global.
-    const globalShim = new shims.Shim(agent, 'globals', 'globals')
-    applyDebugState(globalShim, global)
-    const globalsFilepath = path.join(__dirname, 'instrumentation', 'core', 'globals.js')
-    _firstPartyInstrumentation(agent, globalsFilepath, globalShim, global, 'globals')
-
-    // Instrument each of the core modules.
-    Object.keys(CORE_INSTRUMENTATION).forEach(function forEachCore(mojule) {
-      const core = CORE_INSTRUMENTATION[mojule]
-      const filePath = path.join(__dirname, 'instrumentation', 'core', core.file)
-      let uninstrumented = null
-
-      try {
-        uninstrumented = require(mojule)
-      } catch (err) {
-        logger.trace('Could not load core module %s got error %s', mojule, err)
-      }
-
-      const shim = shims.createShimFromType(core.type, agent, mojule, mojule)
-      applyDebugState(shim, core)
-      _firstPartyInstrumentation(agent, filePath, shim, uninstrumented, mojule)
-    })
-
-    // Register all the first-party instrumentations.
-    Object.keys(INSTRUMENTATIONS).forEach(function forEachInstrumentation(moduleName) {
-      const instrInfo = INSTRUMENTATIONS[moduleName]
+  /**
+   * Registers all instrumentation for "first-party" libraries.
+   *
+   * This is all 3rd party libs with the exception of the domain library in Node.js core
+   *
+   * @param {object} agent NR agent
+   */
+  registerFirstPartyInstrumentation(agent) {
+    for (const [moduleName, instrInfo] of Object.entries(INSTRUMENTATIONS)) {
       if (instrInfo.module) {
         // Because external instrumentations can change independent of
         // the agent core, we don't want breakages in them to entirely
@@ -401,7 +383,7 @@ const shimmer = (module.exports = {
           onRequire: _firstPartyInstrumentation.bind(null, agent, fileName)
         })
       }
-    })
+    }
 
     // Even though domain is a core module we add it as a registered
     // instrumentation to be lazy-loaded because we do not want to cause domain
@@ -414,6 +396,40 @@ const shimmer = (module.exports = {
     })
   },
 
+  /**
+   * Registers all instrumentation for Node.js core libraries.
+   *
+   * @param {object} agent NR agent
+   */
+  registerCoreInstrumentation(agent) {
+    // Instrument global.
+    const globalShim = new shims.Shim(agent, 'globals', 'globals')
+    applyDebugState(globalShim, global)
+    const globalsFilepath = path.join(__dirname, 'instrumentation', 'core', 'globals.js')
+    _firstPartyInstrumentation(agent, globalsFilepath, globalShim, global, 'globals')
+
+    // Instrument each of the core modules.
+    for (const [mojule, core] of Object.entries(CORE_INSTRUMENTATION)) {
+      const filePath = path.join(__dirname, 'instrumentation', 'core', core.file)
+      let uninstrumented = null
+
+      try {
+        uninstrumented = require(mojule)
+      } catch (err) {
+        logger.trace('Could not load core module %s got error %s', mojule, err)
+      }
+
+      const shim = shims.createShimFromType(core.type, agent, mojule, mojule)
+      applyDebugState(shim, core)
+      _firstPartyInstrumentation(agent, filePath, shim, uninstrumented, mojule)
+    }
+  },
+
+  bootstrapInstrumentation: function bootstrapInstrumentation(agent) {
+    shimmer.registerCoreInstrumentation(agent)
+    shimmer.registerFirstPartyInstrumentation(agent)
+  },
+
   registerInstrumentation: function registerInstrumentation(opts) {
     if (!hasValidRegisterOptions(opts)) {
       return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newrelic",
-  "version": "9.13.0",
+  "version": "9.14.0",
   "author": "New Relic Node.js agent team <nodejs@newrelic.com>",
   "license": "Apache-2.0",
   "contributors": [