Configuration options
editConfiguration options
editThe available configuration options and equivalent environment variable names are listed below. Most configuration options can be set in one of three ways:
- By using environment variables
-
In the optional
options
object - 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 ofpackage.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 ofpackage.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
editWhen 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:
- 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.
- 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
editWhen 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:
- 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.
- 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 theCookie
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.