This page describes the available settings that configure the Node.js Agent.

You can use environment variables for some of the settings. To apply the settings, add them to the require statement for the Node.js Agent in the monitored application.   

General Settings

This is the complete list of settings in the require statement that you insert into your application code. Not all of these settings are required.

Property NameDescription
controllerHostNameThe IP address or hostname of your Controller. For SaaS, you will receive this URL in your welcome email from AppDynamics. For on-premises, you will set these when you install the Controller.

The port to which the agent connects to the Controller. It is 8090 for an on-premises Controller and 443 for a SaaS Controller. 

controllerSslEnabledSet this property to true if connecting to the Controller via SSL.
accountNameThe account name on the Controller to which this agent will report.
accountAccessKeyAccount access key on the Controller.
applicationNameName that represents the entire application in the AppDynamics console.
tierNameName that represents your Node.js app or service in the flow maps.
nodeNameName of the Node.js process to be monitored by this agent. See Node Names.
noNodeNameSuffixOptional, set to true if you do not want the agent to add a suffix, such as -0, -1, -2, and so on, to the node name. See Node Names.
proxyHost, proxyPortSet these options to route data to the Controller through a proxy server. The proxyHost is the hostname or IP address of the proxy server. The proxyPort is the proxy server's HTTP or HTTPS port, whichever you are using. If you set the host, you must set the port as well.
proxyUser, proxyPasswordFileConfigure the proxy username and password file if the proxy server requires credentials.
proxySet this property to true if you want to use the Java proxy version of the Node.js Agent.
alwaysAddEumMetadataInHttpHeadersSet this property to true to have the Node.js Agent write business transaction metadata to the XHR header and in a cookie even if the request is considered cross-origin. See the description for the equivalent setting always-add-eum-metadata-in-http-headers in App Agent Node Properties Reference
btEntryPointDelayDisabledtrue | false - Optional, defaults to false. Setting this property to true can accelerate the startup of business transactions, but it can adversely affect the drill-down in distributed transactions.
debugSet this property to true to enable debug level logging for the agent. The default is false.
loggingThe location, level, and other settings related to agent logging. See Node.js Agent Logging.
maxProcessSnapshotsPerPeriodOptional. The default is 2. The number of automatic process snapshots allowed in processSnapshotCountResetPeriodSeconds seconds. 
processSnapshotCountResetPeriodSecondsOptional. The default is 60. Frequency, in seconds, at which the automatic process snapshot count is reset to 0.

Optional. The default is 10. Length, in seconds, of automatically-triggered process snapshots.


true | false - Optional, defaults to false. Set this property to true if you need to manually launch the proxy for this agent. See Start the Proxy Manually for Node.js. 

proxyCtrlDirDirectory path for the directory containing the domain control socket, which the agent uses to start an AppDynamics node. Optional, set by the agent. Set manually if you are setting up a multi-tenant proxy. See Share a Proxy Among Node.js Agents.

Directory path for the root of the directory that stores the agent files. Optional, defaults to /tmp/appds.

tmpDirDirectory path for the subdirectory of the root directory for the monitored node. Optional, defaults to a hash of the Controller info for the instrumented node.
reuseNodeSet this property to true to enable reusing node names. This property is useful for monitoring environments where there are many nodes with short life spans. The default is false.
reuseNodePrefixSet this property to the string that prefixes the node name when reuseNode is set to true. The Controller uses this prefix to generate node names dynamically.
certificateFileDirectory path for the directory containing the .pem SSL certificate.
uniqueHostIdThe unique host ID can be set to any value that will identify the host. If a value is not specified, the agent will generate the host ID. This setting is only available for the proxyless version of the Node.js Agent.

Analytics Settings

You can configure the Node.js Agent to send default transaction data to the Analytics Agent.

To add a setting for the Analytics host and port with the following format, specify the host and port numbers. The Analytics Agent may report on the same or different host and port numbers from the Node.js Agent.

analytics: {
    host: <analyticsHostName>,
    port: <analyticsPort>,
    ssl: <true || false>  

To configure Analytics data limits, see Configure Transaction Analytics for Node.js and PHP Applications.

Windows Settings

On Windows, the Node.js Agent requires three additional ports:

  • proxyCommPort: default is 10101
  • proxyRequestPort: default is 10102
  • proxyReportingPort: default is 10103

See Run the Node.js Agent on Windows for more information.

Filter Sensitive Data

If your application contains sensitive data that should not be displayed in the Controller, you can apply the following data filters to the require statement of the Node.js Agent.

Add a Sensitive Data Filter

When you enable a sensitive data filter, the Controller displays asterisks for the values of matching environment variables or system properties.

dataFilters: [{
   "appliesTo": "http-headers",
   "matchPattern": "host"

Environment Variable Filter

By default, the Node.js Agent enables a sensitive data filter with an environment variables/system properties that contain the case-insensitive substring password|key.

dataFilters: [{
   "appliesTo": "env-vars",
   "matchPattern": "password|key"

Sensitive URL Filter

You can use sensitive URL filters to configure the agent to obfuscate sensitive information from the URLs in the Transaction Snapshot details.

urlFilters: [{
   "delimiter": "/",
   "segment": "1",
   "matchPattern": "a",
   "paramPattern": "bar"

The sensitive URL filter checks for the matchPattern in one segment. To check for additional segments, you can add an additional JSON array.

The filter processes requests in the following format: /aa/bb/cc → ***/bb/cc

The matchpattern/parampattern is a standard regex.

Property NameDescription
An array that you can add more objects to if you want more rules on the segment.
Specifies the desired character as the URL segment endpoints. The agent splices the URL at each delimiter instance to create the segments.
Needs to be at least one number and in ascending order (such as 3,5 or 2,6). Wildcards (*) are not possible.

URL Segment Filter

With the matchpattern regex, the Node.js Agent decides whether or not to filter a specified segment.

If you have multiple rules, list the more specific rule before the more general rule. The rules listed in the array are evaluated based on order. 

Rule A:

 'delimiter': '/',
 'matchPattern': '[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}\/.{50,}',
 'segment': '3,5'

Rule B:

 'delimiter': '/',
 'matchPattern': '[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}',
 'segment': '3'

In this example, the first rule, Rule A, should be listed before Rule B because rule A masks the third and fifth segment.

If Rule B were to be listed and evaluated before Rule A, the third segment will be masked and the fifth segment will not masked, potentially revealing sensitive information. 

URL Parameter Filter

With the paramPattern regex, the Node.js Agent decides whether or not to filter a specified query parameter. 

If you need to mask all URL parameters, you can add further instruction to the array.

{ "delimiter": "/", "matchPattern": "", "segment": "99", "paramPattern": ".+"}

The Node.js Agent will filter out all URL parameters. 

Sensitive Message Filter

You can use sensitive message filters to configure the agent to obfuscate sensitive information contained within text messages collected by the agent from log messages or detail messages from exceptions.

messageFilters: [{
   "redactionRegex": "SQL"

Environment Variables

If you have not provided the required settings in the require statement, the agent uses the values of the following environment variables if those variables are set. If both are set, the require statement value takes precedence over the environment variable.

Environment VariableMaps to
APPDYNAMICS_LOGGER_OUTPUT_TYPEYou can stream logs to stdout by setting its value to console.


You can set the logging level of the agent.

Possible values include: FATAL, ERROR, WARN, INFO, DEBUG, and TRACE.

APPDYNAMICS_ANALYTICS_PORTport—in Analytics settings


The unique host ID can be set to any value that will identify the host. If a value is not specified, the agent will generate the host ID.

This environment variable is available by default (not for Java proxy mode).