Skip to content

Latest commit

 

History

History
71 lines (52 loc) · 5.71 KB

File metadata and controls

71 lines (52 loc) · 5.71 KB

Custom Instrumentation

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

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.