Configuration in Node.js


This section lists the Sqreen Node.js agent configuration options.

Configuration sources

The Sqreen agent reads its configuration from different places. The order of precedence is:

  • Environment variables
  • A JSON file
  • Default configuration options

The JSON file can be located in:

  • Your application top level directory: sqreen.json
  • In a custom place set by SQREEN_CONFIG_FILE environment variable:

export SQREEN_CONFIG_FILE=/custom/path/sqreen.json

Project root and configuration file position

It is recommended that the sqreen.json file is positioned at the same level as the package.json one.

If the application is not started from the directory where the package.json or the sqreen.json is placed, agent needs to be made aware of where to find them. This can be done using the SQREEN_CONFIG_FILE and SQREEN_APP_ROOT environment variables.

Instead of starting the process with:

$ node index.js

it should be started with the following:

$ SQREEN_CONFIG_FILE=/path/to/sqreen.json SQREEN_APP_ROOT=/path/to/application/root node index.js

Where /path/to/sqreen.json is the path to the sqreen.json file and /path/to/application/root is the path to the directory where the package.json file and the node_modules directory are.

With Sqreen agent after 1.30.0, agent tries to detect the application root based on its installation directory.

Configuration variables

You can use environment variables or a JSON file to configure the Sqreen agent. The SQREEN_TOKEN is required. The other settings are optional. Here are the available settings:

Env variable name Role JSON key name Default value
SQREEN_TOKEN The Sqreen token. This identifies the agent to Sqreen backend servers token Empty
SQREEN_CONFIG_FILE Custom location for the JSON based config Empty
SQREEN_LOG_LOCATION Specify a custom file to write Sqreen logs log_location log/sqreen.log
SQREEN_LOG_LEVEL Sqreen logging level log_level WARN
SQREEN_HTTP_PROXY HTTP proxy server http_proxy Empty
SQREEN_IP_HEADER Specify the header to use to find the real IP address of a client ip_header Empty
SQREEN_APP_ROOT Declare custom root directory for project app_root process.cwd()
SQREEN_DISABLE_STARTUP_WARNING Stop logging a warning when the agent isn't required first Not applicable 0 (Enabled)
SQREEN_STRIP_SENSITIVE_DATA Remove sensitive data before sending them to Sqreen BackEnd strip_sensitive_data 1
SQREEN_STRIP_SENSITIVE_REGEX Regular expression used for value stripping, refer to dedicated section below for details strip_sensitive_regex see here for default values
SQREEN_STRIP_SENSITIVE_KEYS Comma separated list of keys to strip, refer to dedicated section below for details strip_sensitive_keys see here for default values

PII scrubbing

Unless strip_sensitive_data is set to false, the Sqreen agent redacts certain data before sending to Sqreen's servers. It redacts the values of key-value pairs listed in strip_sensitive_keys (compared in a case insensitive manner), and redacts any values, including array elements, but not keys, that fully match the strip_sensitive_regex configuration setting.

You can find default PII scrubbing values in PII Scrubbing.

Changing strip_sensitive_keys or strip_sensitive_regex overrides the defaults. So you need to append your extra keys to the list of predefined keys and combine the default regular expression with your new one.

For instance, preventing Sqreen from collecting values matching the regular expression /\d{3}-\d{2}-\d{4}/ can be done by adding the following claim in the sqreen.json file:

{
  "strip_sentitive_regex": [
    "^\\d{3}-\\d{2}-\\d{4}$"
  ]
}

Please notice that adding too many regular expressions could introduce a performance impact in the application.