Configuration options

Your Elastic APM service name.

Allowed characters: a-z, A-Z, 0-9, -, _, and space.

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.

Activate APM Agent Configuration via Kibana. If set to true, the client will poll the APM Server regularly for new agent configuration.

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 URLs 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

The HTTP headers of incoming HTTP requests, and its resulting response headers, are recorded and sent to the APM Server by default. This can be disabled by setting this option to false.

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 for when an aborted TCP connection with an un-ended HTTP request is considered an error. The value is expected to be in seconds, or should include a time suffix.

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.

Set this option to true to use the URL path as the transaction name if no other route could be determined. If the agent do not support your router, you can set this option to true to use specific URL path as the transaction name instead of GET unknown route.

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 itself.

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 itself.

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. It is expressed in bytes or includes a size suffix such as 2kb. Size suffixes are case-insensitive and include b, kb, mb, and gb. 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 open HTTP request to the APM Server that is used to transmit the collected transactions, spans, and errors to the server.

To avoid issues with intermittent proxies and load balancers, the HTTP request is ended and a new one created at regular intervals controlled by this config option. The value is expected to be in seconds, or should include a time suffix.

The agent maintains an open HTTP request to the APM Server that is used to transmit the collected transactions, spans, and errors to the server.

To avoid issues with intermittent proxies and load balancers, the HTTP request is ended and a new one created if its body becomes too large. That limit is controlled by this config option. The value is expected to be in bytes, or include a size suffix such as 1mb. Size suffixes are case-insensitive and include b, kb, mb, and gb.

Specify the response timeout when reporting transactions to APM Server. The timeout should be in seconds, or should include a time suffix.

The timeout is applied once the agent has sent the entire request body to the APM Server. If the response from the server takes longer than allowed by this timeout, the HTTP request is terminated and the TCP socket closed.

When tracing an incoming HTTP request, the agent will add metadata about the requests to the recorded transaction. The same applies for errors that occur 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 one of the filtering functions.

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.

Specify the docker container id to associate with all reported events. If absent, it will be parsed out of the /proc/self/cgroup file.

Specify the kubernetes node name to associate with all reported events.

Specify the kubernetes namespace to associate with all reported events.

Specify the kubernetes pod name to associate with all reported events. If absent, and if kubernetesPodUID is parsed out of the /proc/self/cgroup file, this will default to the local hostname.

Specify the kubernetes pod uid to associate with all reported events. If absent, it will be parsed out of the /proc/self/cgroup file.

Specify the interval for reporting metrics to APM Server. The interval should be in seconds, or should include a time suffix.

To disable metrics reporting, set the interval to 0.

Specify the maximum number of metrics to track at any given time. When a new metric is inserted which would exceed the limit, the oldest metric will be dropped to give it space.

Supply a key/value pair object of labels to apply to any data recorded by the agent.

Example:

ELASTIC_APM_GLOBAL_LABELS="subspace=sap-hana,rack=number6"

The Node.js agent will look for a file named elastic-apm-node.js in the current working directory. You can specify a custom path using this config option (this path must include the filename), e.g:

ELASTIC_APM_CONFIG_FILE=/path/to/my-elastic-apm-node.js

The configuration file is expected to export an object, following the same conventions as the options object, given as the first argument to the start function, e.g.:

module.exports = {
  // Override service name from package.json
  // Allowed characters: a-z, A-Z, 0-9, -, _, and space
  serviceName: '',

  // Use if APM Server requires a token
  secretToken: '',

  // Set custom APM Server URL (default: http://localhost:8200)
  serverUrl: ''
}

Used to disable reporting of breakdown metrics which records self time spent in each unique type of span.