Agent API

Your Elastic APM service name.

The secret token optionally expected by the APM Server.

The URL to where the APM Server is deployed.

By default the agent will validate the TLS/SSL certificate of the APM Server if using HTTPS. You can switch this behavior off by setting this option to false. Disabling validation is normally required if using self-signed certificates.

The version of the app currently running. This could be the version from your package.json file, a git commit reference, or any other string that might help you pinpoint a specific version or deployment.

A boolean specifying if the agent should be active or not. If active, the agent will instrument incoming HTTP requests and track errors. Normally you would not want to run the agent in your development or testing environments. If you are using the NODE_ENV environment variable, you can use this to determine the state:

var options = {
  active: process.env.NODE_ENV === 'production'
}

A boolean specifying if the agent should collect performance metrics for the app.

Note that both active and instrument needs to be true for instrumentation to be running.

A boolean specifying if the agent should use the experimental Async Hooks API found in Node.js version 8.2.0 and above. This setting has no effect when running a Node.js version older than 8.2.0.

If you experience any issues related to using Async Hooks, please open an issue.

Note that not all core Node.js API’s can be instrumented without the use of Async Hooks if running Node.js 8 or above.

Used to restrict requests to certain URL’s from being instrumented.

This property should be set to an array containing one or more strings or RegExp objects. When an incoming HTTP request is detected, its URL will be tested against each element in this list. If an element in the array is a String, an exact match will be performed. If an element in the array is a RegExp object, its test function will be called with the URL being tested.

Note that all errors that are captured during a request to an ignored URL are still sent to the APM Server regardless of this setting.

Example usage:

require('elastic-apm-node').start({
  ignoreUrls: [
    '/ping',
    /^\/admin\//i
  ]
})

Used to restrict requests from certain User-Agents from being instrumented.

This property should be set to an array containing one or more strings or RegExp objects. When an incoming HTTP request is detected, the User-Agent from the request headers will be tested against each element in this list. If an element in the array is a String, it’s matched against the beginning of the User-Agent. If an element in the array is a RegExp object, its test function will be called with the User-Agent string being tested.

Note that all errors that are captured during a request by an ignored user agent are still sent to the APM Server regardless of this setting.

Example usage:

require('elastic-apm-node').start({
  ignoreUserAgents: [
    'curl/',
    /pingdom/i
  ]
})

The HTTP body of incoming HTTP requests is not recorded and sent to the APM Server by default.

Possible options are: off, all, errors, and transactions.

The recorded body will be truncated if larger than 2 KiB.

For the agent to be able to access the body, the body needs to be available as a property on the incoming HTTP request object. The agent will look for the body on the following properties: req.json || req.body || req.payload

A boolean specifying if the agent should monitor for aborted TCP connections with un-ended HTTP requests. An error will be generated and sent to the APM Server if this happens.

Specify the threshold (in milliseconds) for when an aborted TCP connection with an un-ended HTTP request is considered an error.

If the errorOnAbortedRequests property is false, this property is ignored.

Specify the sampling rate to use when deciding whether to trace a request.

The value should between 0.0 and 1.0 where 1.0 is 100% of all requests.

The OS hostname is automatically logged along with all errors and transactions. If you want to overwrite this, use this option.

Set the name of the web framework used by the instrumented service / application. The name will be available as metadata for all errors and transactions sent to the APM Server. This can be useful for debugging and filtering.

By default, the agent will set the value of this config option if the framework can be detected automatically.

Set the version of the web framework used by the instrumented service / application. The version will be available as metadata for all errors and transactions sent to the APM Server. This can be useful for debugging and filtering.

By default, the agent will set the value of this config option if the framework can be detected automatically.

Example of setting frameworkName and frameworkVersion for a framework named my-custom-framework:

// read the version from the package.json file
var frameworkVersion = require('my-custom-framework/package').version

require('elastic-apm-node').start({
  frameworkName: 'my-custom-framework',
  frameworkVersion: frameworkVersion
})

Set the verbosity level for the agent. Note that this does not have any influence on the types of errors that are sent to the APM Server. This only controls how chatty the agent is in your logs. This only applies when not using a custom logger.

Possible levels are: trace, debug, info, warn, error, and fatal.

Set a custom logger, e.g. bunyan:

require('elastic-apm-node').start({
  logger: require('bunyan')({ level: 'info' })
})

If no custom logger is provided, the agent will use its built-in logger which will log to STDOUT and STDERR depending on the log level.

The logger should expose the following functions: trace, debug,info, warn, error, and fatal.

Note that if a custom logger is provided, the logLevel option will be ignored.

Whether or not the agent should monitor for uncaught exceptions and send them to the APM Server automatically.

Normally only Error objects have a stack trace associated with them. This stack trace is stored along with the error message when the error is sent to the APM Server. The stack trace points to the place where the Error object was instantiated.

But sometimes its valuable to know, not where the Error was instantiated, but where it was detected. For instance, when an error happens deep within a database driver, the location where the error bubbles up to, is sometimes more useful for debugging, than where the error occurred.

Set this config option to always to — besides the error stack trace — also capture a stack trace at the location where captureError was called.

By default, this config option has the value messages, which means that a stack trace of the capture location will be recorded only when captureError is called with either a string or the special parameterized message object, in which case a normal stack trace isn’t available.

Set this config option to never to never record a capture location stack trace.

A capture location stack trace is never generated for uncaught exceptions.

Set this option to false to disable capture of stack traces for measured spans during instrumentation.

When an error is captured by the agent, its stack trace is stored in Elasticsearch.

By default the agent will also collect a few lines of source code around the lines for each frame in the stack trace. This can make it easier to determine the cause of an error as the source code related to the error is visible directly in Kibana.

The agent differentiates between so called in-app frames and library frames. Library frames are frames belonging to Node core and code inside the applications node_modules folder. In-app frames are everything else.

Use the following two config options to change how many lines of source code to include for the different types of stack frames:

sourceLinesErrorAppFrames

The default value 5 means that 5 lines of source code will be collected for in-app error frames. 2 lines above the stack frame line + 2 below + the stack frame line it self.

Setting this config option to 0 means that no source code will be collected for in-app error frames.

sourceLinesErrorLibraryFrames

The default value 5 means that 5 lines of source code will be collected for error library frames. 2 lines above the stack frame line + 2 below + the stack frame line it self.

Setting this config option to 0 means that no source code will be collected for error library frames.

When a span is recorded by the agent, a stack trace is recorded together with the span, pointing to the location where the span was initiated. This stack trace is stored in Elasticsearch along with the other span data.

By default the agent will also collect a few lines of source code around the lines for each frame in the stack trace. This can make it easier to determine why and how the span was initiated as the source code related to the span is visible directly in Kibana.

The agent differentiates between so called in-app frames and library frames. Library frames are frames belonging to Node core and code inside the applications node_modules folder. In-app frames are everything else.

Use the following two config options to change how many lines of source code to include for the different types of stack frames:

sourceLinesSpanAppFrames

The default value 0 means that no source code will be collected for in-app span frames.

sourceLinesSpanLibraryFrames

The default value 0 means that no source code will be collected for span library frames.

The maximum length allowed for error messages in bytes. Messages above this length will be truncated before being sent to the APM Server.

Set to -1 do disable truncation.

This applies to the following properties:

Setting it to 0 will disable stack trace collection. Any finite integer value will be used as the maximum number of frames to collect. Setting it to Infinity means that all frames will be collected.

Specify the maximum number of spans to capture within a request transaction before dropping further spans. Setting to -1 means that spans will never be dropped.

The agent maintains an in-memory queue to which recorded transactions are added when they end. Unless empty, this queue is flushed and sent to the APM Server for processing approximately every 10 seconds.

Use this option to change that interval. The value is expected to be in seconds.

Lowering this interval can reduce memory usage on Node.js applications with a high number of transactions.

Specify the timeout in seconds when reporting transactions to APM Server.

The agent maintains an in-memory queue to which recorded transactions are added when they end. The queue is flushed with regular intervals controlled by the flushInterval config option.

Use the maxQueueSize option to force a flush of the queue when it reaches a certain size (number of ended transactions) - even if the flushInterval time isn’t reached yet.

Set to -1 to disable, in which case only flushInterval counts.

When tracing an incoming HTTP request, the agent will add metadata about the requests to the recorded transaction. The same applies for errors that occurs and are captured as a result of the request.

This boolean specifies if the agent should anonymize certain sensitive HTTP headers by default before they are sent to the APM Server. When anonymized, the header value will be set to [REDACTED]

Currently the following HTTP headers are anonymized by default:

If you wish to filter or sanitize other data, use the apm.addFilter() function.

Array or comma-separated string of modules to disable instrumentation for. When instrumentation is disabled for a module, no spans will be collected for that module.

Example using options object:

require('elastic-apm-node').start({
  disableInstrumentations: ['graphql', 'express-graphql']
})

Example using environment variable:

ELASTIC_APM_DISABLE_INSTRUMENTATIONS=graphql,express-graphql

For an always up-to-date list of modules for which instrumentation can be disabled, see the lib/instrumentation/modules folder in the agent repository. Note that not all modules represented in this directory will generate spans, and adding those to this array has no effect.

Instead of an Error object, you can log a plain text message:

apm.captureError('Something happened!')

This will also be sent as an error to the APM Server, but will not be associated with an exception.

Instead of an Error object or a string, you can supply a special parameterized message object:

apm.captureError({
  message: 'Could not find user %s with id %d in the database',
  params: ['Peter', 42]
})

This makes it possible to better group error messages that contain variable data like ID’s or names.

To ease debugging it’s possible to send some extra data with each error you send to the APM Server. The APM Server intake API supports a lot of different metadata fields, most of which are automatically managed by the Elastic APM Node.js Agent. But if you wish you can supply some extra details using user or custom. For more details on the properties accepted by the error intake API see the intake error API docs.

To supply any of these extra fields, use the optional options argument when calling apm.captureError().

Here are some examples:

// Sending some extra details about the user
apm.captureError(error, {
  user: {
    id: 'unique_id',
    username: 'foo',
    email: 'foo@example.com'
  }
})

// Sending some arbitrary details using the `custom` field
apm.captureError(error, {
  custom: {
    some_important_metric: 'foobar'
  }
})

To supply per-request metadata to all errors captured in one central location, use apm.setUserContext() and apm.setCustomContext().

Besides the options described in the metadata section, you can use the options argument to associate the error with an HTTP request:

apm.captureError(err, {
  request: req // an instance of http.IncomingMessage
})

This will log the URL that was requested, the HTTP headers, cookies and other useful details to help you debug the error.

In most cases this isn’t needed though, as the agent is pretty smart at figuring out if your Node.js app is an HTTP server and if an error occurred during an incoming request. In which case it will automate this processes for you.

Besides the options described in the metadata section, you can use the options argument to associate the error with an HTTP response:

apm.captureError(err, {
  response: res // an instance of http.ServerResponse
})

This will log the response status code, headers and other useful details to help you debug the error.

In most cases this isn’t needed though, as the agent is pretty smart at figuring out if your Node.js app is an HTTP server and if an error occurred during an incoming request. In which case it will automate this processes for you.