Skip to main content

Configure the Node.js agent

The standard configuration for all agents uses this order of precedence.

There are several ways to configure the Node.js agent, but generally, you should:

  • Use a YAML configuration file to set configuration values that are common for all applications in an organization or container (for example, to redirect logging or proxy configuration). This template shows all valid configuration options for the Node.js agent. Learn more about YAML configuration in general.

  • Use environment variables for agent authentication keys and application-specific configuration values. Learn more about environment variables in general.


Use the Contrast agent configuration editor to create or upload a YAML configuration file, validate YAML, and get setting recommendations. The editor also provides the correct environment variables, if desired.

Environment variables

Use environment variables for application-specific configuration values (like configuring server environment, application names or agent logging). You can also use environment variables to set any other valid properties for the Node.js agent.

You can see a full list of valid properties in the Node.js YAML template, but here are some common examples as environment variables:

Environment variable



Set the service key needed to communicate with Contrast.


Set the API key needed to communicate with Contrast.


Set the user name needed to communicate with Contrast.


Set the URL for the Contrast web interface.


Override the reported application name.


When set, supersedes the default location of the YAML configuration file. (Unlike other environment variables, this one cannot be set as a YAML property, and contains only single underscores.)


Override the reported server path.


Provides a consistent server name for cases where containerized apps generate many server records.   This could be the microservice name or app name.


Creates configuration and system files at startup to help track diagnostic and troubleshooting information. Default is true.


When set to false, creates a new log file on startup instead of appending and rolling daily. Default is true.


Logging level: FATAL, ERROR, WARN, INFO, DEBUG or TRACE. Default is ERROR.


Where Contrast will put its debug log. Default is node-contrast.log.


When set to false, suppresses output to stdout. Default is true.

If you want to redirect logging for the Node.js, contact Support for assistance.


For legacy v4 of the agent:

For the Node.js agent you must manually configure DEBUG. INFO-level statements aren't logged to the console unless the environment variable DEBUG is set to include the Contrast namespace: DEBUG=contrast:*. This could be useful in environments where you don't have access to the file system (like Docker or ECS).

If you want to redirect logging for the Node.js, see more examples on the npm site or contact Support for assistance.