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

You can save the JSON file 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

You should save the sqreen.json file at the same level as the package.json file.

If the application does not start from the directory containing the package.json or the sqreen.json, you must tell the Sqreen agent where to find them. You can do this using the SQREEN_CONFIG_FILE and SQREEN_APP_ROOT environment variables.

Instead of starting the process with:

$ node index.js

Start it 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 containing the package.json file and the node_modules directory.

With Sqreen agents above 1.30.0, the 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 (https://my.sqreen.com/profile/organization/tokens). Your token has the prefix org_.

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

You can provide this information using the SQREEN_TOKEN and SQREEN_APP_NAME environment variables.

When using the application token, only the SQREEN_TOKEN is required.

Application tokens deprecated

Application tokens are unique to an application. 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 deprecated, and we encourage you to convert your applications to use organization tokens as soon as possible.

Follow this how-to to migrate applications using an application token.

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_CUSTOM_PKG_SUBSTRING_IGNORE Agent will ignore packages with a certain substring in alerts regarding first required packages
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 information 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 need to 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": [
    "^\\d{3}-\\d{2}-\\d{4}$"
  ]
}

Adding a large number of regular expressions could affect the application's performance.