newrelic 9.2.0 → 9.3.0

package/NEWS.md

@@ -1,3 +1,13 @@
+### v9.3.0 (2022-10-17)
+
+* Added instrumentation to bunyan to support application logging use cases: forwarding, local decorating, and metrics.
+   
+   Big thanks to @brianphillips for his contribution 🚀
+
+* Added c8 to track code coverage.
+
+* Added documentation about custom instrumentation in ES module applications
+
 ### v9.2.0 (2022-10-06)
 
 * Added ability to instrument ES Modules with the New Relic ESM Loader.

package/README.md

@@ -84,6 +84,47 @@ $ node --experimental-loader newrelic/esm-loader.mjs your-program.js
 
 **Note**: Unlike the CommonJS methods listed above, there are no alternatives to running the agent without the `--experimental-loader` flag.
 
+### Custom Instrumentation
+
+The agent supports adding your own custom instrumentation to ES module applications. In order to load custom instrumentation in an ES module app, you'll need to update your `newrelic.cjs` file to include the following:
+
+```js
+    /* File: newrelic.cjs */
+    'use strict'
+    /**
+     * New Relic agent configuration.
+     *
+     * See lib/config/default.js in the agent distribution for a more complete
+     * description of configuration variables and their potential values.
+     */
+    exports.config = {
+      app_name: ['Your application or service name'],
+      license_key: 'your new relic license key',
+      api: {
+        esm: {
+            custom_instrumentation_entrypoint: '/path/to/my/instrumentation.js'
+        }
+      }
+      /* ... rest of configuration .. */
+    }
+```
+
+If you do not use a configuration file, then use the environment variable `NEW_RELIC_API_ESM_CUSTOM_INSTRUMENTATION_ENTRYPOINT` instead.
+
+By updating the configuration, the agent's ES module loader will ensure that your custom instrumentation is added at module load. This is required in ES module applications due to the immutability of module export bindings: we are unable to apply our instrumentation after loading is complete.
+
+We support the following custom instrumentation API methods in ES module apps:
+
+* `newrelic.instrument`
+* `newrelic.instrumentConglomerate`
+* `newrelic.instrumentDatastore`
+* `newrelic.instrumentMessages`
+* `newrelic.instrumentWebframework`
+
+Note that we _do not_ support `newrelic.instrumentLoadedModule`, for the same issue of immutability mentioned above.
+
+If you want to see an example of how to write custom instrumentation in an ES module app, check out our [examples](https://github.com/newrelic/newrelic-node-examples/tree/main/esm-app) repo for a working demo.
+
 ## Getting Started
 
 For more information on getting started, [check the Node.js docs](https://docs.newrelic.com/docs/agents/nodejs-agent/getting-started/introduction-new-relic-nodejs).

package/THIRD_PARTY_NOTICES.md

@@ -37,6 +37,7 @@ code, the source code can be found at [https://github.com/newrelic/node-newrelic
 * [@slack/bolt](#slackbolt)
 * [ajv](#ajv)
 * [async](#async)
+* [c8](#c8)
 * [chai](#chai)
 * [commander](#commander)
 * [eslint-config-prettier](#eslint-config-prettier)
@@ -2091,6 +2092,28 @@ THE SOFTWARE.
 
 ```
 
+### c8
+
+This product includes source derived from [c8](https://github.com/bcoe/c8) ([v7.12.0](https://github.com/bcoe/c8/tree/v7.12.0)), distributed under the [ISC License](https://github.com/bcoe/c8/blob/v7.12.0/LICENSE.txt):
+
+```
+Copyright (c) 2017, Contributors
+
+Permission to use, copy, modify, and/or distribute this software
+for any purpose with or without fee is hereby granted, provided
+that the above copyright notice and this permission notice
+appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE
+LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+```
+
 ### chai
 
 This product includes source derived from [chai](https://github.com/chaijs/chai) ([v4.3.6](https://github.com/chaijs/chai/tree/v4.3.6)), distributed under the [MIT License](https://github.com/chaijs/chai/blob/v4.3.6/LICENSE):

package/lib/instrumentation/bunyan.js

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2022 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const {
+  isApplicationLoggingEnabled,
+  isLogForwardingEnabled,
+  isLocalDecoratingEnabled,
+  isMetricsEnabled,
+  createModuleUsageMetric,
+  incrementLoggingLinesMetrics
+} = require('../util/application-logging')
+
+const MAX_LENGTH = 1021
+const OUTPUT_LENGTH = 1024
+const truncate = (str) => {
+  if (str && str.length > OUTPUT_LENGTH) {
+    return str.substring(0, MAX_LENGTH) + '...'
+  }
+
+  return str
+}
+
+const logger = require('../logger').child({ component: 'bunyan' })
+
+function augmentLogData(originalLog, agent, nameFromLevel) {
+  // shallow copy, since we're modifying things
+  const newLog = Object.assign({}, originalLog)
+  newLog.timestamp = Date.now()
+  newLog.level = nameFromLevel[originalLog.level]
+
+  // put log message into a consistent spot and ensure it's not too long
+  newLog.message = truncate(newLog.msg)
+
+  // tidy up the error output to help with max length restrictions
+  if (newLog.err) {
+    newLog['error.message'] = truncate(newLog.err.message)
+    newLog['error.stack'] = truncate(newLog.err.stack)
+    newLog['error.class'] =
+      newLog.err.name === 'Error' ? newLog.err.constructor.name : newLog.err.name
+    // clear out the old error message
+    delete newLog.err
+  }
+
+  // Add the metadata to the object being logged
+  const metadata = agent.getLinkingMetadata(true)
+  Object.keys(metadata).forEach((m) => {
+    newLog[m] = metadata[m]
+  })
+
+  return newLog
+}
+
+function createLoggerWrapper(shim, fn, fnName, bunyanLogger, nameFromLevel) {
+  const agent = shim.agent
+
+  createModuleUsageMetric('bunyan', agent.metrics)
+
+  // forward logs via the agent logs aggregator
+  bunyanLogger.addStream({
+    name: 'NRLogForwarder',
+    type: 'raw',
+    level: bunyanLogger.level(),
+    stream: {
+      write: function nrLogWrite(logLine) {
+        agent.logs.add(augmentLogData(logLine, agent, nameFromLevel))
+      }
+    }
+  })
+  // no return here means the original return value is preserved
+}
+
+module.exports = function instrument(agent, bunyan, _, shim) {
+  const config = agent.config
+
+  if (!isApplicationLoggingEnabled(config)) {
+    logger.debug('Application logging not enabled. Not instrumenting bunyan.')
+    return
+  }
+
+  const logForwardingEnabled = isLogForwardingEnabled(config, agent)
+  const localDecoratingEnabled = isLocalDecoratingEnabled(config)
+  const metricsEnabled = isMetricsEnabled(config)
+
+  if (logForwardingEnabled) {
+    shim.wrapReturn(bunyan, 'createLogger', createLoggerWrapper, [bunyan.nameFromLevel])
+  }
+
+  if (metricsEnabled || localDecoratingEnabled) {
+    shim.wrap(bunyan.prototype, '_emit', function wrapEmit(_shim, emit) {
+      return function wrappedEmit() {
+        const args = shim.argsToArray.apply(shim, arguments)
+        const rec = args[0]
+
+        if (metricsEnabled) {
+          incrementLoggingLinesMetrics(bunyan.nameFromLevel[rec.level], agent.metrics)
+        }
+
+        if (localDecoratingEnabled) {
+          rec.message = truncate(rec.msg) + agent.getNRLinkingMetadata()
+        }
+        args[0] = rec
+        return emit.apply(this, args)
+      }
+    })
+  }
+}

package/lib/instrumentations.js

@@ -15,6 +15,7 @@ module.exports = function instrumentations() {
     'cassandra-driver': { type: MODULE_TYPE.DATASTORE },
     'connect': { type: MODULE_TYPE.WEB_FRAMEWORK },
     'bluebird': { type: MODULE_TYPE.PROMISE },
+    'bunyan': { type: MODULE_TYPE.GENERIC },
     'director': { type: MODULE_TYPE.WEB_FRAMEWORK },
     'express': { type: MODULE_TYPE.WEB_FRAMEWORK },
     'fastify': { type: MODULE_TYPE.WEB_FRAMEWORK },

package/lib/metrics/names.js

@@ -277,11 +277,13 @@ const LOGGING = {
     INFO: `${LOGGING_LINES_PREFIX}/INFO`,
     WARN: `${LOGGING_LINES_PREFIX}/WARN`,
     ERROR: `${LOGGING_LINES_PREFIX}/ERROR`,
+    FATAL: `${LOGGING_LINES_PREFIX}/FATAL`,
     DEBUG: `${LOGGING_LINES_PREFIX}/DEBUG`,
     TRACE: `${LOGGING_LINES_PREFIX}/TRACE`,
     UNKNOWN: `${LOGGING_LINES_PREFIX}/UNKNOWN`
   },
   LIBS: {
+    BUNYAN: `${SUPPORTABILITY.LOGGING}/${NODEJS.PREFIX}bunyan/enabled`,
     PINO: `${SUPPORTABILITY.LOGGING}/${NODEJS.PREFIX}pino/enabled`,
     WINSTON: `${SUPPORTABILITY.LOGGING}/${NODEJS.PREFIX}winston/enabled`
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newrelic",
-  "version": "9.2.0",
+  "version": "9.3.0",
   "author": "New Relic Node.js agent team <nodejs@newrelic.com>",
   "license": "Apache-2.0",
   "contributors": [
@@ -146,7 +146,7 @@
     "bench": "node ./bin/run-bench.js",
     "docker-env": "./bin/docker-env-vars.sh",
     "docs": "npm ci && jsdoc -c ./jsdoc-conf.json --private -r .",
-    "integration": "npm run prepare-test && npm run sub-install && time tap test/integration/**/**/*.tap.js --timeout=180 --no-coverage --reporter classic",
+    "integration": "npm run prepare-test && npm run sub-install && time c8 -o ./coverage/integration tap test/integration/**/**/*.tap.js --timeout=180 --no-coverage --reporter classic",
     "prepare-test": "npm run ssl && npm run docker-env",
     "lint": "eslint ./*.{js,mjs} lib test bin examples",
     "lint:fix": "eslint --fix, ./*.{js,mjs} lib test bin examples",
@@ -158,8 +158,8 @@
     "sub-install": "node test/bin/install_sub_deps",
     "test": "npm run integration && npm run unit && npm run unit:esm",
     "third-party-updates": "oss third-party manifest --includeOptDeps && oss third-party notices --includeOptDeps && git add THIRD_PARTY_NOTICES.md third_party_manifest.json",
-    "unit": "rm -f newrelic_agent.log && time tap --test-regex='(\\/|^test\\/unit\\/.*\\.test\\.js)$' --timeout=180 --no-coverage --reporter classic",
-    "unit:esm": "rm -f newrelic_agent.log && time tap --test-regex='(\\/|^test\\/unit\\/.*\\.test\\.mjs)$' --timeout=180 --no-coverage --reporter classic --node-arg=--experimental-loader=testdouble",
+    "unit": "rm -f newrelic_agent.log && time c8 -o ./coverage/unit tap --test-regex='(\\/|^test\\/unit\\/.*\\.test\\.js)$' --timeout=180 --no-coverage --reporter classic",
+    "unit:esm": "rm -f newrelic_agent.log && time c8 -o ./coverage/esm-unit --include *.mjs --include **/*.mjs --exclude false tap --test-regex='(\\/|^test\\/unit\\/.*\\.test\\.mjs)$' --timeout=180 --no-coverage --reporter classic --node-arg=--experimental-loader=testdouble",
     "update-cross-agent-tests": "./bin/update-cats.sh",
     "versioned-tests": "./bin/run-versioned-tests.sh",
     "update-changelog-version": "node ./bin/update-changelog-version",
@@ -199,6 +199,7 @@
     "@slack/bolt": "^3.7.0",
     "ajv": "^6.12.6",
     "async": "^3.2.4",
+    "c8": "^7.12.0",
     "chai": "^4.1.2",
     "commander": "^7.0.0",
     "eslint": "^8.24.0",