Configuration options

edit

The available configuration options and equivalent environment variable names are listed below. Most configuration options can be set in one of three ways:

  1. By using environment variables
  2. In the optional options object
  3. Via the agent configuration file.

For more information on setting configuration options, see configuring the agent.

The only required parameter is serviceName. However, the agent will use the name from package.json by default if available.

serviceName

edit
  • Type: String
  • Default: name field of package.json
  • Env: ELASTIC_APM_SERVICE_NAME

Your Elastic APM service name.

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

secretToken

edit
  • Type: String
  • Env: ELASTIC_APM_SECRET_TOKEN

The secret token optionally expected by the APM Server.

serverUrl

edit
  • Type: String
  • Default: http://localhost:8200
  • Env: ELASTIC_APM_SERVER_URL

The URL to where the APM Server is deployed.

verifyServerCert

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_VERIFY_SERVER_CERT

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.

serviceVersion

edit
  • Type: String
  • Default: version field of package.json
  • Env: ELASTIC_APM_SERVICE_VERSION

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.

active

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_ACTIVE

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'
}

environment

edit
  • Type: String
  • Default: process.env.NODE_ENV || 'development'
  • Env: ELASTIC_APM_ENVIRONMENT

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

Environments allow you to easily filter data on a global level in the APM app. It’s important to be consistent when naming environments across agents. See environment selector in the APM app for more information.

This feature is fully supported in the APM app in Kibana versions >= 7.2. You must use the query bar to filter for a specific environment in versions prior to 7.2.

instrument

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_INSTRUMENT

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.

centralConfig

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_CENTRAL_CONFIG

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

This feature requires APM Server v7.3 or later and that the APM Server is configured with kibana.enabled: true. More information is available in APM Agent configuration.

asyncHooks

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_ASYNC_HOOKS

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.

ignoreUrls

edit
  • Type: Array
  • Default: undefined

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
  ]
})

ignoreUserAgents

edit
  • Type: Array
  • Default: undefined

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
  ]
})

captureBody

edit
  • Type: String
  • Default: off
  • Env: ELASTIC_APM_CAPTURE_BODY

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.

  • off - request bodies will never be reported
  • errors - request bodies will only be reported with errors
  • transactions - request bodies will only be reported with request transactions
  • all - request bodies will be reported with both errors and request 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

captureHeaders

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_CAPTURE_HEADERS

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.

errorOnAbortedRequests

edit
  • Type: Boolean
  • Default: false
  • Env: ELASTIC_APM_ERROR_ON_ABORTED_REQUESTS

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.

abortedErrorThreshold

edit
  • Type: Number
  • Default: 25s
  • Env: ELASTIC_APM_ABORTED_ERROR_THRESHOLD

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.

transactionSampleRate

edit
  • Type: Number
  • Default: 1.0
  • Env: ELASTIC_APM_TRANSACTION_SAMPLE_RATE

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.

hostname

edit
  • Type: String
  • Default: OS hostname
  • Env: ELASTIC_APM_HOSTNAME

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

frameworkName

edit
  • Type: String
  • Env: ELASTIC_APM_FRAMEWORK_NAME

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.

frameworkVersion

edit
  • Type: String
  • Env: ELASTIC_APM_FRAMEWORK_VERSION

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
})

logLevel

edit
  • Type: String
  • Default: 'info'
  • Env: ELASTIC_APM_LOG_LEVEL

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.

logger

edit
  • Type: object

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.

captureExceptions

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_CAPTURE_EXCEPTIONS

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

captureErrorLogStackTraces

edit
  • Type: String
  • Default: messages
  • Env: ELASTIC_APM_CAPTURE_ERROR_LOG_STACK_TRACES

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.

captureSpanStackTraces

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_CAPTURE_SPAN_STACK_TRACES

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

usePathAsTransactionName

edit
  • Type: Boolean
  • Default: false
  • Env: ELASTIC_APM_USE_PATH_AS_TRANSACTION_NAME

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.

sourceLinesErrorAppFrames + sourceLinesErrorLibraryFrames

edit

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

  • Type: Number
  • Default: 5
  • Env: ELASTIC_APM_SOURCE_LINES_ERROR_APP_FRAMES

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

  • Type: Number
  • Default: 5
  • Env: ELASTIC_APM_SOURCE_LINES_ERROR_LIBRARY_FRAMES

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.

sourceLinesSpanAppFrames + sourceLinesSpanLibraryFrames

edit

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

  • Type: Number
  • Default: 0
  • Env: ELASTIC_APM_SOURCE_LINES_SPAN_APP_FRAMES

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

sourceLinesSpanLibraryFrames

  • Type: Number
  • Default: 0
  • Env: ELASTIC_APM_SOURCE_LINES_SPAN_LIBRARY_FRAMES

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

errorMessageMaxLength

edit
  • Type: String
  • Default: 2kb
  • Env: ELASTIC_APM_ERROR_MESSAGE_MAX_LENGTH

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:

  • error.exception.message
  • error.log.message

stackTraceLimit

edit
  • Type: Number
  • Default: 50
  • Env: ELASTIC_APM_STACK_TRACE_LIMIT

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.

transactionMaxSpans

edit
  • Type: Number
  • Default: 500
  • Env: ELASTIC_APM_TRANSACTION_MAX_SPANS

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.

apiRequestTime

edit
  • Type: String
  • Default: 10s
  • Env: ELASTIC_APM_API_REQUEST_TIME

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 HTTP request is ended before the time threshold is reached if enough bytes are sent over it. Use the apiRequestSize config option to control the byte threshold.

apiRequestSize

edit
  • Type: String
  • Default: 768kb
  • Env: ELASTIC_APM_API_REQUEST_SIZE

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.

The HTTP request is otherwise ended at regular intervals controlled by the apiRequestTime config option.

serverTimeout

edit
  • Type: String
  • Default: 30s
  • Env: ELASTIC_APM_SERVER_TIMEOUT

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.

filterHttpHeaders

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_FILTER_HTTP_HEADERS

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:

  • Authorization - The full value of this header is redacted
  • Cookie - The cookies inside the Cookie header are analyzed and their values redacted if they appear sensitive (like a session cookie). See the is-secret module for details about which patterns are considered sensitive.

If you wish to filter or sanitize other data, use one of the filtering functions.

disableInstrumentations

edit
  • Type: Array of strings
  • Env: ELASTIC_APM_DISABLE_INSTRUMENTATIONS

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.

containerId

edit
  • Type: String
  • Env: ELASTIC_APM_CONTAINER_ID

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

kubernetesNodeName

edit
  • Type: String
  • Env: KUBERNETES_NODE_NAME

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

kubernetesNamespace

edit
  • Type: String
  • Env: KUBERNETES_NAMESPACE

Specify the kubernetes namespace to associate with all reported events.

kubernetesPodName

edit
  • Type: String
  • Env: KUBERNETES_POD_NAME

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.

kubernetesPodUID

edit
  • Type: String
  • Env: KUBERNETES_POD_UID

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

metricsInterval

edit
  • Type: String
  • Default: 30s
  • Env: ELASTIC_APM_METRICS_INTERVAL

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.

metricsLimit

edit
  • Type: Number
  • Default: 1000
  • Env: ELASTIC_APM_METRICS_LIMIT

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.

globalLabels

edit
  • Type: Object
  • Env: ELASTIC_APM_GLOBAL_LABELS

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"

configFile

edit
  • Type: String
  • Default: elastic-apm-node.js
  • Env: ELASTIC_APM_CONFIG_FILE

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 inline version of this config option, that is passed to the start function, will be ignored if a config file was already loaded when this module was required (based on either the default value or because of the ELASTIC_APM_CONFIG_FILE environment variable).

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: ''
}

breakdownMetrics

edit
  • Type: Boolean
  • Default: true
  • Env: ELASTIC_APM_BREAKDOWN_METRICS

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