README.md

Custom Instrumentation

This folder contains example applications using the Agent API to do custom instrumentation.

• Instrument library code
  • instrument - example application that uses the newrelic.instrument API and associated shim API to instrument a simple library
  • instrumentDatastore - example application that uses the newrelic.instrumentDatastore API and datastore shim API to instrument a toy datastore called Simple Datastore
  • instrumentWebframework - example application that uses the newrelic.instrumentWebframework API and associated WebFramework shim API to instrument a hypothetical web framework
  • instrumentMessages - example application that uses the newrelic.instrumentMessages API and associated messaging shim API to instrument a toy messaging library called Nifty Messages
• Attributes, Events, and Metrics - example application that demonstrates how to create custom attributes, events, and metrics.
• Background Transactions - example application that uses the newrelic API to create background transactions
• Distributed tracing - example application that demonstrates distributed tracing
• Segments - example application that demonstrates how to use the newrelic.startSegment API in a variety of cases: callback-based, promise-based, asyncronously, and syncronously
• Start Web Transaction - example application that demonstrates how to use newrelic.startWebTransaction.
• URL Obfuscation - example application that demonstrates how to use url_obfuscation rules to scrub PII from span names and attributes.

Purpose of Instrumentation

Instrumentation for Node.js holds two purposes. The first is to give users detailed information about what happens on their server. The more things instrumented, the more detailed your dashboard graphs will be. The second purpose is to maintain the transaction context; this is done by the context manager and is explained in more detailed in the instrument example app.

Adding Custom Instrumentation to the New Relic Agent

Calling require('newrelic') will return an API object, which contains the following methods for registering custom instrumentation:

• instrument
• instrumentDatastore
• instrumentWebframework
• instrumentMessages

These methods are used to tell the New Relic agent to use the provided instrumentation function when the specified module is loaded by Node. It is critically important that we register our instrumentation before the module is loaded anywhere. For example:

var newrelic = require('newrelic')
newrelic.instrument('my-module', instrumentMyModule)
var myModule = require('my-module')

All four methods have the same signature. The difference between them is in what type of shim they provide when the instrumentation function is called. The instrument method provides only the base shim, while instrumentDatastore, instrumentWebframework, and instrumentMessages provide shims specific to the type of instrumentation (DatastoreShim, WebFrameworkShim, and MessageShim respectively).

The instrument call could have also been written using named parameters like this:

newrelic.instrument({
  moduleName: 'my-module',
  onRequire: instrumentMyModule
})

This call is equivalent to the first one, it just depends on your preferred style.

Handling Errors

While debugging your instrumentation it can be useful to get a handle on any errors happening within it. Normally, the agent swallows errors and disables the instrumentation. In order to get the error for your debugging purposes you can provide a third argument to instrument that receives the error.

newrelic.instrument({
  moduleName: 'my-module',
  onRequire: instrumentMyCustomModule,
  onError: function myErrorHandler(err) {
    // Uh oh! Our instrumentation failed, let's see why:
    console.error(err.message, err.stack)

    // Let's kill the application when debugging so we don't miss it.
    process.exit(1)
  }
})

Questions?

We have an extensive help site as well as documentation. If you can't find your answers there, please drop us a line on the community forum.