newrelic 2.0.0 → 2.2.0

package/.eslintrc

@@ -4,6 +4,7 @@
     "browser": false
   },
   "globals": {
+    "Map": true,
     "Promise": true
   },
   "rules": {

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+## CHANGE LOG
+
+## INTERNAL LINKS
+
+## NOTES

package/NEWS.md

@@ -1,4 +1,79 @@
 
+### v2.2.0 (2017-08-22):
+* Added support for ignoring ranges of status codes.
+
+  The configuration `error_collector.ignore_status_codes` can now take ranges
+  of numbers. For example, `ignore_status_codes: ['400-404']` would ignore 400,
+  401, 402, 403, and 404.
+
+* Fixed a bug when a custom collector port was provided in the configuration
+  that prevented redirected connections from working.
+
+* Fixed a bug in `Shim#record` that could cause an exception when trying to
+  create a new segment as part of an ended/inactive transaction.
+
+* Fixed issue with custom Hapi handlers causing an error.
+
+  Previously custom Hapi handlers defined using the `server.handler()` method
+  were causing the Hapi server to return a 500 error. Now they are correctly
+  handled and recorded as middleware functions.
+
+* Transaction state is now maintained in `ChildProcess` event listeners.
+
+* Updated examples and documentation regarding custom transaction creation.
+
+  All examples and documentation now point at the `newrelic.start*Transaction`
+  methods.
+
+* Reducing logging verbosity in the SQL query obfuscator.
+
+* Experimental instrumentation for `async/await`
+
+  This is experimental instrumentation and has not yet been tested in a wide
+  array of production environments. The feature is currently off by default
+  behind a feature flag. To enable this experimental instrumentation, add
+  `await_support: true` to the `feature_flag` setting in your agent config
+  file.
+
+### v2.1.0 (2017-08-08):
+* Improved metadata collection for AWS, Azure, GCE, and Pivotal Cloud Foundry.
+
+* Fixed a bug in PG query obfuscation for `$` placeholders.
+
+  The agent used to mis-detect `$1` value placeholders as unmatched
+  dollar-quoted strings causing the whole query to be obfuscated to just `?`.
+  These placeholders are now correctly detected and obfuscated.
+
+### v2.0.2 (2017-08-01):
+* Improved documentation for `newrelic.start*Transaction` and `TransactionHandle.`
+
+  Formatting for the `startWebTransaction` and `startBackgroundTransaction`
+  methods was fixed and documentation for the `TransactionHandle` class which
+  `getTransaction` returns was added.
+
+* Fixed parsing the table name from SQL queries.
+
+  Quotes around the table name are now stripped after parsing the query and
+  before constructing the metrics.
+
+* Fixed unhandled rejection error caused by `ioredis` instrumentation.
+
+### v2.0.1 (2017-07-25):
+* Fixed issue with transaction events not including correct duration values.
+
+  This issue was introduced in v2.0.0, and it has affected web transactions histogram
+  and percentile charts.
+
+* Fixed issue with Redis instrumentation causing the agent to crash in some cases.
+
+  Previously, the Redis instrumentation would crash the agent when Redis commands were
+  called without a callback and after the transaction has ended.
+
+* Fixed issue with the agent crashing on Node v4.0-4.4 and v5.0-5.9.
+
+  This issue was caused by incorrect shim for Buffer.from(), and it affected older minor
+  versions of Node v4 and v5.
+
 ### v2.0.0 (2017-07-17):
 * [The New Relic Node Agent v2 is here!](https://blog.newrelic.com/2017/07/18/nodejs-agent-v2-api/)
 

package/README.md

@@ -656,7 +656,7 @@ application, the agent can't tell when they should begin and end.
 Read more at:
 https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-custom-instrumentation
 
-#### newrelic.createWebTransaction(url, handle)
+#### newrelic.startWebTransaction(url, handle)
 
 `url` is the name of the web transaction. It should be pretty static, not
 including anything like user ids or any other data that is very specific to the
@@ -669,16 +669,22 @@ called within an active background transaction, it will create a new,
 independent transaction and any calls within the `handle` will be bound to the
 new web transaction.
 
-Custom transactions **must** be ended manually by calling `endTransaction()`.
-Timing for custom transaction starts from when the returned wrapped function is
-called until `endTransaction()` is called.
+Custom transactions can be ended within the `handle` in one of three ways:
 
-#### newrelic.createBackgroundTransaction(name, [group], handle)
+1. Call `transaction.end()`. The `transaction` can be received by calling
+  `newrelic.getTransaction()` first thing in the handler function. Then,
+  when you call `transaction.end()` timing will stop.
+2. Return a promise. The transaction will end when the promise resolves or
+  rejects.
+3. Do neither. If no promise is returned, and `getTransaction()` isn't
+  called, the transaction will end immediately after the handle returns.
+
+#### newrelic.startBackgroundTransaction(name [, group], handle)
 
 `name` is the name of the job. It should be pretty static, and not include job
 ids or anything very specific to that run of the job. `group` is optional, and
 allows you to group types of jobs together. This should follow similar rules as
-the `name`. `handle` is a function that encompases your background job. Both
+the `name`. `handle` is a function that encompasses your background job. Both
 custom and auto instrumentation will be captured as part of the transaction.
 
 If called within an active background transaction, it will act as a nested
@@ -686,14 +692,20 @@ tracer. If called within an active web transaction, it will create a new
 transaction and any calls within the `handle` will be bound to the new,
 independent background transaction.
 
-Custom transactions **must** be ended manually by calling `endTransaction()`.
-Timing for custom transaction starts from when the returned wrapped function is
-called until `endTransaction()` is called.
+1. Call `transaction.end()`. The `transaction` can be received by calling
+  `newrelic.getTransaction()` first thing in the handler function. Then,
+  when you call `transaction.end()` timing will stop.
+2. Return a promise. The transaction will end when the promise resolves or
+  rejects.
+3. Do neither. If no promise is returned, and `getTransaction()` isn't
+  called, the transaction will end immediately after the handle returns.
 
-#### newrelic.endTransaction()
+#### newrelic.getTransaction()
 
-This takes no arguments and must be called to end any custom transaction. It
-will detect what kind of transaction was active and end it.
+This takes no arguments and returns the currently active transaction. If the
+returned transaction is a custom one, started with either `startWebTransaction`
+or `startBackgroundTransaction`, then `transaction.end()` must be called to
+end the transaction.
 
 #### newrelic.createTracer(name, handle)
 

package/api.js

@@ -91,6 +91,7 @@ API.prototype.setTransactionName = function setTransactionName(name) {
     return
   }
 
+  logger.trace('Setting transaction %s name to %s', transaction.id, name)
   transaction.forceName = NAMES.CUSTOM + '/' + name
 }
 
@@ -102,7 +103,7 @@ API.prototype.setTransactionName = function setTransactionName(name) {
  * - ignore: set the transaction that was active when
  *   `API#getTransaction` was called to be ignored.
  *
- * @returns {object} transaction The transaction object with the `end`
+ * @returns {TransactionHandle} transaction The transaction object with the `end`
  *                               and `ignore` methods on it.
  */
 API.prototype.getTransaction = function getTransaction() {
@@ -622,6 +623,15 @@ API.prototype.createTracer = function createTracer(name, callback) {
   return arity.fixArity(callback, tracer.bindFunction(callback, segment, true))
 }
 
+API.prototype.createWebTransaction = util.deprecate(
+  createWebTransaction, [
+    'API#createWebTransaction is being deprecated!',
+    'Please use API#startWebTransaction for transaction creation',
+    'and API#getTransaction for transaction management including',
+    'ending transactions.'
+  ].join(' ')
+)
+
 /**
  * Creates a function that represents a web transaction. It does not start the
  * transaction automatically - the returned function needs to be invoked to start it.
@@ -638,16 +648,11 @@ API.prototype.createTracer = function createTracer(name, callback) {
                                 related transactions in APM, so it should be a generic
                                 name and not iclude any variable parameters.
  * @param {Function}  handle    Function that represents the transaction work.
+ *
+ * @memberOf API#
+ *
+ * @deprecated since version 2.0
  */
-API.prototype.createWebTransaction = util.deprecate(
-  createWebTransaction,
-  [
-    'API#createWebTransaction is being deprecated!',
-    'Please use API#startWebTransaction and API#getTransaction',
-    'for transaction creation and management.'
-  ].join(' ')
-)
-
 function createWebTransaction(url, handle) {
   var metric = this.agent.metrics.getOrCreateMetric(
     NAMES.SUPPORTABILITY.API + '/createWebTransaction'
@@ -710,9 +715,9 @@ function createWebTransaction(url, handle) {
  * synchronously returns UNLESS:
  * 1. The handle function returns a promise, where the end of the
  *    transaction will be tied to the end of the promise returned.
- * 2. `API#getTransaction` is called in the handle, flagging the
+ * 2. {@link API#getTransaction} is called in the handle, flagging the
  *    transaction as externally handled.  In this case the transaction
- *    will be ended when `Transaction#end` is called in the user's code.
+ *    will be ended when {@link TransactionHandle#end} is called in the user's code.
  *
  * @example
  * var newrelic = require('newrelic')
@@ -731,9 +736,7 @@ function createWebTransaction(url, handle) {
  * @param {Function}  handle
  *  Function that represents the transaction work.
  */
-API.prototype.startWebTransaction = startWebTransaction
-
-function startWebTransaction(url, handle) {
+API.prototype.startWebTransaction = function startWebTransaction(url, handle) {
   var metric = this.agent.metrics.getOrCreateMetric(
     NAMES.SUPPORTABILITY.API + '/startWebTransaction'
   )
@@ -784,15 +787,17 @@ function startWebTransaction(url, handle) {
   })()
 }
 
+API.prototype.startBackgroundTransaction = startBackgroundTransaction
+
 /**
  * Creates and starts a background transaction to record work done in
  * the handle supplied. This transaction will run until the handle
  * synchronously returns UNLESS:
  * 1. The handle function returns a promise, where the end of the
  *    transaction will be tied to the end of the promise returned.
- * 2. `API#getTransaction` is called in the handle, flagging the
+ * 2. {@link API#getTransaction} is called in the handle, flagging the
  *    transaction as externally handled.  In this case the transaction
- *    will be ended when `Transaction#end` is called in the user's code.
+ *    will be ended when {@link TransactionHandle#end} is called in the user's code.
  *
  * @example
  * var newrelic = require('newrelic')
@@ -816,9 +821,9 @@ function startWebTransaction(url, handle) {
  *
  * @param {Function} handle
  *  Function that represents the background work.
+ *
+ * @memberOf API#
  */
-API.prototype.startBackgroundTransaction = startBackgroundTransaction
-
 function startBackgroundTransaction(name, group, handle) {
   var metric = this.agent.metrics.getOrCreateMetric(
     NAMES.SUPPORTABILITY.API + '/startBackgroundTransaction'
@@ -878,6 +883,15 @@ function startBackgroundTransaction(name, group, handle) {
   })()
 }
 
+API.prototype.createBackgroundTransaction = util.deprecate(
+  createBackgroundTransaction, [
+    'API#createBackgroundTransaction is being deprecated!',
+    'Please use API#startBackgroundTransaction for transaction creation',
+    'and API#getTransaction for transaction management including',
+    'ending transactions.'
+  ].join(' ')
+)
+
 /**
  * Creates a function that represents a background transaction. It does not
  * start the transaction automatically - the returned function needs to be
@@ -908,16 +922,11 @@ function startBackgroundTransaction(name, group, handle) {
  * @return {Function} The `handle` function wrapped with starting a new
  *  transaction. This function can be called repeatedly to start multiple
  *  transactions.
+ *
+ * @memberOf API#
+ *
+ * @deprecated since version 2.0
  */
-API.prototype.createBackgroundTransaction = util.deprecate(
-  createBackgroundTransaction,
-  [
-    'API#createBackgroundTransaction is being deprecated!',
-    'Please use API#startBackgroundTransaction and API#getTransaction',
-    'for transaction creation and management.'
-  ].join(' ')
-)
-
 function createBackgroundTransaction(name, group, handle) {
   var metric = this.agent.metrics.getOrCreateMetric(
     NAMES.SUPPORTABILITY.API + '/createBackgroundTransaction'
@@ -983,6 +992,10 @@ function createBackgroundTransaction(name, group, handle) {
   return arity.fixArity(handle, proxy)
 }
 
+/**
+ * End the current web or background custom transaction. This method requires being in
+ * the correct transaction context when called.
+ */
 API.prototype.endTransaction = function endTransaction() {
   var metric = this.agent.metrics.getOrCreateMetric(
     NAMES.SUPPORTABILITY.API + '/endTransaction'
@@ -1011,6 +1024,21 @@ API.prototype.endTransaction = function endTransaction() {
   }
 }
 
+/**
+ * Record an event-based metric, usually associated with a particular duration.
+ * The `name` must be a string following standard metric naming rules. The `value` will
+ * usually be a number, but it can also be an object.
+ *   * When `value` is a numeric value, it should represent the magnitude of a measurement
+ *     associated with an event; for example, the duration for a particular method call.
+ *   * When `value` is an object, it must contain count, total, min, max, and sumOfSquares
+ *     keys, all with number values. This form is useful to aggregate metrics on your own
+ *     and report them periodically; for example, from a setInterval. These values will
+ *     be aggregated with any previously collected values for the same metric. The names
+ *     of these keys match the names of the keys used by the platform API.
+ *
+ * @param  {string} name  The name of the metric.
+ * @param  {number|object} value
+ */
 API.prototype.recordMetric = function recordMetric(name, value) {
   var supportMetric = this.agent.metrics.getOrCreateMetric(
     NAMES.SUPPORTABILITY.API + '/recordMetric'
@@ -1045,7 +1073,7 @@ API.prototype.recordMetric = function recordMetric(name, value) {
 
   for (var i = 0, l = required.length; i < l; ++i) {
     if (typeof value[required[i]] !== 'number') {
-      logger.warn('Metric object must include ' + required[i] + ' as a number')
+      logger.warn('Metric object must include %s as a number', required[i])
       return
     }
 
@@ -1062,6 +1090,14 @@ API.prototype.recordMetric = function recordMetric(name, value) {
   metric.merge(stats)
 }
 
+/**
+ * Update a metric that acts as a simple counter. The count of the selected metric will
+ * be incremented by the specified amount, defaulting to 1.
+ *
+ * @param  {string} name  The name of the metric.
+ * @param  {number} [value] The amount that the count of the metric should be incremented
+ *                          by.
+ */
 API.prototype.incrementMetric = function incrementMetric(name, value) {
   var metric = this.agent.metrics.getOrCreateMetric(
     NAMES.SUPPORTABILITY.API + '/incrementMetric'
@@ -1091,6 +1127,15 @@ API.prototype.incrementMetric = function incrementMetric(name, value) {
   })
 }
 
+/**
+ * Record an event-based metric, usually associated with a particular duration.
+ *
+ * @param  {string} eventType  The name of the event. It must be an alphanumeric string
+ *                             less than 255 characters.
+ * @param  {object} attributes Object of key and value pairs. The keys must be shorter
+ *                             than 255 characters, and the values must be string, number,
+ *                             or boolean.
+ */
 API.prototype.recordCustomEvent = function recordCustomEvent(eventType, attributes) {
   var metric = this.agent.metrics.getOrCreateMetric(
     NAMES.SUPPORTABILITY.API + '/recordCustomEvent'

package/index.js

@@ -17,6 +17,9 @@ if (require.cache.__NR_cache) {
     'Attempting to load a second copy of newrelic from %s, using cache instead',
     __dirname
   )
+  if (require.cache.__NR_cache.agent) {
+    require.cache.__NR_cache.agent.recordSupportability('Agent/DoubleLoad')
+  }
   module.exports = require.cache.__NR_cache
 } else {
   initialize()
@@ -88,9 +91,10 @@ function initialize() {
       agent.start(function cb_start(error) {
         if (!error) {
           // TODO: After deprecating Node 0.10 and 0.12, simplify this regex.
+          // TODO: As new versions come out, make sure to update Angler metrics.
           var nodeMajor = /^v?((?:0\.)?\d+)/.exec(process.version)
-          agent.metrics.getOrCreateMetric(
-            'Supportability/Nodejs/Version/' + ((nodeMajor && nodeMajor[1]) || 'unknown')
+          agent.recordSupportability(
+            'Version/' + ((nodeMajor && nodeMajor[1]) || 'unknown')
           )
 
           return logger.debug("New Relic for Node.js is connected to New Relic.")

package/lib/agent.js

@@ -107,6 +107,7 @@ function Agent(config) {
   this.segmentsCreatedInHarvest = 0
   this.segmentsClearedInHarvest = 0
   this.activeTransactions = 0
+  this.transactionCreatedInHarvest = 0
 
   // Hidden class optimizations.
   this.harvesterHandle = null
@@ -286,9 +287,11 @@ Agent.prototype.harvest = function harvest(callback) {
     harvestCleared: this.segmentsClearedInHarvest,
     activeTransactions: this.activeTransactions
   }, 'Entity stats on harvest')
+  this.recordSupportability('Transactions/Created', this.transactionCreatedInHarvest)
 
   this.segmentsCreatedInHarvest = 0
   this.segmentsClearedInHarvest = 0
+  this.transactionCreatedInHarvest = 0
 
   if (!this.collector.isConnected()) {
     return process.nextTick(function cb_nextTick() {
@@ -860,10 +863,10 @@ Agent.prototype._addIntrinsicAttrsFromTransaction = _addIntrinsicAttrsFromTransa
 
 function _addIntrinsicAttrsFromTransaction(transaction) {
   var intrinsicAttributes = {
-    webDuration: transaction.timer.duration / 1000,
+    webDuration: transaction.timer.getDurationInMillis() / 1000,
     timestamp: transaction.timer.start,
     name: transaction.name,
-    duration: transaction.timer.duration / 1000,
+    duration: transaction.timer.getDurationInMillis() / 1000,
     type: 'Transaction',
     error: transaction.hasErrors()
   }
@@ -994,7 +997,7 @@ Agent.prototype._transactionFinished = function _transactionFinished(transaction
     logger.debug('Ignoring %s (%s).', transaction.name, transaction.id)
   }
 
-  this.activeTransactions--
+  --this.activeTransactions
   this.totalActiveSegments -= transaction.numSegments
   this.segmentsClearedInHarvest += transaction.numSegments
 }
@@ -1008,4 +1011,13 @@ Agent.prototype.getTransaction = function getTransaction() {
   return this.tracer.getTransaction()
 }
 
+Agent.prototype.recordSupportability = function recordSupportability(name, value) {
+  var metric = this.metrics.getOrCreateMetric(NAMES.SUPPORTABILITY.NODEJS + '/' + name)
+  if (value != null) {
+    metric.recordValue(value)
+  } else {
+    metric.incrementCallCount()
+  }
+}
+
 module.exports = Agent

package/lib/collector/api.js

@@ -42,11 +42,11 @@ var HTTP_LOL_COLLECTOR = 503
 function dumpErrors(errors, name) {
   var index = 1
 
-  errors.forEach(function cb_forEach(error) {
+  errors.forEach(function forEachError(error) {
     logger.trace(error, "Error %s during %s:", index++, name)
 
     if (error.laterErrors) {
-      error.laterErrors.forEach(function cb_forEach(laterError) {
+      error.laterErrors.forEach(function forEachLaterError(laterError) {
         logger.trace(laterError, "Error %s during %s:", index++, name)
       })
     }
@@ -115,7 +115,7 @@ CollectorAPI.prototype.connect = function connect(callback) {
     var id = setTimeout(function again() {
       api._login(retry)
     }, backoff.interval * TO_MILLIS)
-    
+
     if (id.unref) {
       id.unref()
     }
@@ -129,7 +129,7 @@ CollectorAPI.prototype._login = function _login(callback) {
   var agent = this._agent
 
 
-  methods.redirect.invoke(null, function cb_invoke(error, collector, body) {
+  methods.redirect.invoke(null, function redirectCb(error, collector, body) {
     if (error) return callback(error, collector, body)
     if (!collector) {
       logger.error(
@@ -152,18 +152,20 @@ CollectorAPI.prototype._login = function _login(callback) {
         )
 
         agent.config.host = parts[0]
-        if (parts.length > 1) {
-          agent.config.port = parts[1]
-        }
+        agent.config.port = parts[1] || (agent.config.ssl ? 443 : 80)
       }
     }
 
+    _getFacts()
+  })
+
+  function _getFacts() {
     facts(agent, function getEnvDict(environmentDict) {
       // The collector really likes arrays.
       // In fact, it kind of insists on them.
       var environment = [environmentDict]
 
-      methods.handshake.invoke(environment, function cb_invoke(error, config, body) {
+      methods.handshake.invoke(environment, function handshakeCb(error, config, body) {
         if (error) return callback(error, config, body)
         if (!config || !config.agent_run_id) {
           return callback(new Error("No agent run ID received from handshake."), config)
@@ -183,7 +185,7 @@ CollectorAPI.prototype._login = function _login(callback) {
         callback(null, config, body)
       })
     })
-  })
+  }
 }
 
 /**

package/lib/collector/facts.js

@@ -10,7 +10,7 @@ function facts(agent, callback) {
     var hostname = agent.config.getHostnameSafe()
     var results = {
       utilization: {
-        metadata_version: 2,
+        metadata_version: 3,
         logical_processors: systemInfo.logicalProcessors,
         total_ram_mib: systemInfo.memory,
         hostname: hostname
@@ -36,18 +36,18 @@ function facts(agent, callback) {
       results.app_name.concat([]).sort().join(',')
     ].join(':')
 
-    if (systemInfo.aws || systemInfo.docker) {
-      results.utilization.vendors = {}
-      if (systemInfo.aws) {
-        results.utilization.vendors.aws = systemInfo.aws
-      }
-      if (systemInfo.docker) {
-        results.utilization.vendors.docker = systemInfo.docker
-      }
+    if (systemInfo.bootId) {
+      results.utilization.boot_id = systemInfo.bootId
     }
+
+    if (systemInfo.vendors) {
+      results.utilization.vendors = systemInfo.vendors
+    }
+
     if (systemInfo.config) {
       results.utilization.config = systemInfo.config
     }
+
     return callback(results)
   })
 }

package/lib/config.default.js

@@ -245,12 +245,34 @@ exports.config = {
      */
     detect_aws: true,
     /**
-     * This flag dictates whether the agent attempts to reach out to AWS
+     * This flag dictates whether the agent attempts to detect if the
+     * the process is running on Pivotal Cloud Foundary.
+     *
+     * @env NEW_RELIC_UTILIZATION_DETECT_PCF
+     */
+    detect_pcf: true,
+    /**
+     * This flag dictates whether the agent attempts to reach out to Azure to
+     * get info about the vm the process is running on.
+     *
+     * @env NEW_RELIC_UTILIZATION_DETECT_AZURE
+     */
+    detect_azure: true,
+    /**
+     * This flag dictates whether the agent attempts to read files
      * to get info about the container the process is running in.
      *
      * @env NEW_RELIC_UTILIZATION_DETECT_DOCKER
      */
-    detect_docker: true
+    detect_docker: true,
+
+    /**
+     * This flag dictates whether the agent attempts to reach out to GCP
+     * to get info about the vm the process is running on.
+     *
+     * @env NEW_RELIC_UTILIZATION_DETECT_GCP
+     */
+    detect_gcp: true
   },
   transaction_tracer: {
     /**