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

Find your organization token by going to Account Settings > Tokens in your Sqreen dashboard, or ( Your token is prefixed with org_.

To help Sqreen correctly identify the application when you use an organization token, you also need to set a unique application name.

Those information can be provided using the SQREEN_TOKEN and SQREEN_APP_NAME environment variables. When using the application token, only the SQREEN_TOKEN is required.

Application tokens depreciated

Appplication tokens are dedicated to an application, and organization tokens are available throughout the organization your account belongs to.

While Sqreen will continue to support application tokens for backward compatibility in the short term, they are now depreciated, and we encourage you to convert your applications to use organization tokens as soon as possible.

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_APP_NAME The application name as displayed within the Sqreen dashboard app_name 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 you set strip_sensitive_data 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. You should append your extra keys to the list of predefined keys and combine the default regular expression with your new one.

For instance, to prevent Sqreen from collecting values matching the regular expression /\d{3}-\d{2}-\d{4}/ add the following claim in the sqreen.json file:

  "strip_sentitive_regex": [

Adding too many regular expressions could introduce a performance impact in the application.