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.


It is also possible to use command line arguments for some configurations.

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.


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.


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.

Node.js YAML template

Use this template to configure the Node.js agent using a YAML configuration file.