Configure the Node.js microagent

The Sqreen Microagent reads three sources for its configuration. It follows the configurations from these sources in sequence. The order of precedence is as follows:

  1. environment variables
  2. a sqreen.json file
  3. default configuration options

Configuration variables

The table below lists the variables you can use to customize the Sqreen microagent's configuration. For boolean configuration items, the "Allowed values" column is impacting the Environment variable usage. In sqreen.json, please use booleans.

Environment variable name Role JSON key name Default value Allowed values
SQREEN_TOKEN The token is the identifier the Sqreen Platform uses to identify the microagent. Access your token in Account Settings > Environments & Tokens. token empty string
SQREEN_APP_NAME The application name as displayed on the Sqreen Dashboard. app_name empty string
SQREEN_CONFIG_FILE Specifies a custom location for the JSON-based config file. empty string
SQREEN_LOG_LOCATION Specifies a custom file to which the microagent writes logs. log_location log/sqreen.log string
SQREEN_LOG_LEVEL Sets the microagent logging level. log_level WARN FATAL ERROR WARN INFO DEBUG
SQREEN_HTTP_PROXY Specifies an HTTP proxy server for the microagent's connection to the Sqreen Platform. http_proxy empty proxy URI (http://proxy:port )
SQREEN_IP_HEADER Specifies the header to use to extract the real IP address of a client. ip_header empty header name (case insensitive)
SQREEN_APP_ROOT Declares a custom root directory for project. app_root process.cwd()
SQREEN_CUSTOM_PKG_SUBSTRING_IGNORE Specifies packages with a defined substring in alerts that the microagent ignores.
SQREEN_DISABLE_STARTUP_WARNING Stops logging a warning when require('sqreen') is not executing first in the main module of your application. Not applicable 0 (enabled) 0 (enabled), 1 (disabled)
SQREEN_STRIP_SENSITIVE_DATA Removes personally identifiable information (PII) before the microagent sends metadata to the Sqreen Platform. Refer to PII scrubbing below for details. strip_sensitive_data 1 (enabled) 1 (enabled), 0 (disabled)
SQREEN_STRIP_SENSITIVE_REGEX Regular expression that removes specific sensitive information before the microagent sends metadata to the Sqreen Platform. Refer to PII scrubbing below for details. strip_sensitive_regex empty (uses default values) (arbitrary)
SQREEN_STRIP_SENSITIVE_KEYS Comma-separated list of keys that removes specific sensitive information before the microagent sends metadata to the Sqreen Platform. Refer to PII scrubbing below for details. strip_sensitive_keys empty (uses default values) (arbitrary)
SQREEN_USE_WORKSPACE Make Sqreen check for node_modules in current directory and the parent one use_workspace Empty 1 (enabled)
SQREEN_WORKSPACE_DEPTH When used with use_workspace, specify how many parent directories to look in workspace_depth Empty 1 (enabled)

JSON file

The Sqreen Microagent stores configurations in the sqreen.json file. The microagent detects the application root based on its installation folder. Save the sqreen.json file and the the package.json file in the top level folder in your application.

If you wish, you can customize a location for the JSON file.

  1. Use the SQREEN_CONFIG_FILE environment variable to specify a custom location in your application's directory.
    export SQREEN_CONFIG_FILE=/custom/path/sqreen.json
  2. If the application does not start from the directory containing the package.json or the sqreen.json files, you must specify the location where the Sqreen microagent can find them.
    • Use the SQREEN_CONFIG_FILE environment variable to specify the path to the sqreen.json file.
    • Use the SQREEN_APP_ROOT environment variable to specify the path to the package.json file and the node_modules directory.

Instead of starting the process with...

$ node index.js
... start it with:
$ SQREEN_CONFIG_FILE=/path/to/sqreen.json SQREEN_APP_ROOT=/path/to/application/root node index.js

PII scrubbing

The microagent does not send Personally Identifiable Information (PII) to the Sqreen Platform. With each heartbeat, the microagent scrubs the metadata to remove PII and replace it with Redacted by Sqreen. By default, the microagent scrubs the following values from the metadata it sends:

  • Values that look like they contain credit card numbers, according to a basic regular expression: ^(?:\d[ -]*?){13,16}$
  • Values associated with any of the following keys:
    • password
    • secret
    • passwd
    • authorization
    • api_key
    • apikey
    • Access_token

Turn off PII scrubbing

To turn off PII scrubbing, in the sqreen.json file, set strip_sensitive_data to false (disabled).

Customize PII scrubbing

You can customize the sensitive information that the microagent redacts.

  1. In the sqreen.json file, use strip_sensitive_keys to replace the default values (case insensitive) that the microagent redacts.

  2. In the sqreen.json file, use strip_sensitive_regex to replace the default values, including arrays, that match a regular expression. Be aware that adding a large number of regular expressions to this configuration may affect the application's performance.

For example, to ensure that the microagent redacts values matching the regular expression /\d{3}-\d{2}-\d{4}/, add the following claim in the sqreen.json file:

  "strip_sentitive_regex": [

Replace, not add

Be aware that the values you set in strip_sensitive_keys and strip_sensitive_regex replace the default values that the microagent redacts. In other words, the values you configure here are not added to the default values the microagent redacts, they override them